PC Media 15

home *** CD-ROM | disk | FTP | other *** search

/ PC Media 15 / PC MEDIA CD15.iso / helpline / get27 / get27.doc < prev next >

Wrap

Text File | 1987-11-26 | 244.5 KB | 5,567 lines

*********** Read and Remove this paragraph before printing **************** NOTE: This file is formatted for printing on a laser printer using a utility such as Vern Buerg's LJBOOK laser jet booklet printing utility. This will print 4 pages on one sheet of paper front and back thus forming a convenient book and conserving paper. If you do not have a laser printer or do not use LJBOOK, it is suggested that you set your printer for 8 lines per inch, compressed type, and/or reduce the font point size if possible. ******* Remove this paragraph after reading and before printing *********** USER MANUAL and COMMAND REFERENCE GUIDE for GET.EXE Bob Stephan's Batch File Enhancer Version 2.7 Release 2.70 Manual revision date May 29, 1995 Copyright Bob Stephan 1995 All Rights Reserved This software and user's guide are Copyright 1995 by Bob Stephan and Moby Disk, ALL RIGHTS RESERVED. They are protected by both United States copyright law and international treaty provisions. Edition revision date May 29 Moby Disk is an acronym for MOnterey BaY DISK Data Systems, both of which are registered business names of Bob Stephan. Bob Stephan reserves the right to make changes to this document without notice. Moby Disk 1021 San Carlos Road Pebble Beach CA 93953 Phone: 408-646-1899 FAX: On request CompuServe: 72357,2276 America Online: MobyDisk2 Internet: bob.stephan@nitelog.com CRICKET BBS: (408) 373-3773 NITELOG BBS: (408) 655-1096 IBM, Microsoft, Windows, DESQview, DR DOS, MS-DOS, PC-DOS and 4DOS are trademarks of their respective companies. This document was produced using XyWrite 4.0, a product of The Technology Group. GET.DOC GET Version 2.7 Copyright 1995 Bob Stephan READ.ME GET.EXE is a general purpose DOS BATch file enhancer. It makes information available to the BATch file through the BATch IF subcommand. The information can come from user input or from the operating system, and it is made available to the BATch file through the DOS ErrorLevel (Exit Code) as well as variables in the DOS Environment. GET also has capabilities to set some system parameters and perform a few other specific actions, over 50 functions in all. Not only is GET wonderful for automating your personal system, it is excellent for client support and software installation programs. If you have been using an older version of GET, you will also be interested in the information in GET27NEW.DOC to help focus on the new and improved features. LICENSING SUMMARY GET is copyrighted software and is not in the public domain! The shareware version may be used for limited evaluation period after which time registration is required to obtain a license for continued use. GET is released as shareware with a requested registration fee of $15 plus $2 shipping and handling to U.S.A, Canada, or Mexico, or $4 to other countries. The full manual can be included with new registrations or ordered later by registered users for $8 plus S&H as above. These prices are subject to change. Registered users will be able to obtain upgrades at very reasonable prices. See ORDER.GET for additional pricing information. (California residents please add applicable sales tax.) There are conditions imposed on the distribution of copies of GET. Please read this information and the section on Licensing and Distribution to be sure you are not using GET illegally. The only version of GET that is free for an evaluation period is the one that displays the help screen when the name GET is entered at the DOS prompt by itself. If you have one that says it is licensed and you have not registered, you have a pirated copy that is protected by law. VENDORS, CORPORATE, and COMMERCIAL users see licensing terms under Licensing and Distribution. INDIVIDUALS, SHAREWARE AUTHORS, and SYSOPS. This version of GET is free for a limited evaluation period. Shareware authors who register GET may use it in distributing their products subject to the conditions specified in the Licensing and Distribution terms below. GET.EXE may be freely copied and distributed provided that all files in the GET package, including but not limited to all the .DOC files, are included on the disk or in the compressed file with GET.EXE. Registrations and contributions to support this development project will be gratefully accepted. If you send the registration fee prescribed above (or more) plus the appropriate shipping and handling fee (see the ORDER.GET file) and appropriate sales tax you will receive the following benefits: The latest version of GET with any new features. A licensed runtime version to distribute with your BATch files. A single user license with no royalties for non-commercial use. An option to purchase the user manual giving examples and explanations. Free support by BBS, mail, phone, CompuServe, or America Online (see below). Notification of new releases and upgrades when available. Reduced prices for upgrading to new versions. Page iv READ.ME GET 2.7 AVAILABILITY Various versions of GET are available on many electronic bulletin board systems worldwide, and on the various commercial on-line systems such as CompuServe, America On Line, and GENIE. The latest shareware versions are always available for first time downloads on the following two boards on the Monterey Penninsula in California: NITELOG 408-655-1096 CRICKET 408-373-3773 A brief BBS registration is required for first time callers. FIDONET: GET is available from FIDONET BFDS (Batch File Distribution System) sites. It can also be FREQ'd from Nitelog for those with FIDONET File REQuest access. Various versions of GET are also available at many FTP sites for those with Internet access. REGISTRATION. Registrations in U.S. funds by check, cash, money order, or purchase order can be mailed to the below address. VISA or MASTERCARD orders accepted by phone, or via NITELOG BBS. Enter S for Script, then 3 for Script 3 and complete the order form. COMPUSERVE. GET is available for Shareware registration on CompuServe. Just GO SWREG and place your order. The latest version is available in IBM PC Utilities (GO PCUTIL). SITE LICENSING. Site licensing applies to the number of concurrent users within an organization that are authorized to be using BATch files which require GET, such as on a network. The prices listed are for the maximum number of concurrent users in each bracket. DISTRIBUTION LICENSING. Distribution licensing can be ordered in conjunction with a site or multiple use license solely for placing copies of the runtime module on diskettes for the purpose of distributing software. This license does not include the continued use of GET after the distributed software is installed on the target computer. These prices are solely for making additional copies of the runtime module to place on diskettes, and they do not include any documentation or additional copies of the software. The initial copy of the software must be obtained by licensing according to the above schedule for the number of concurrent users/developers at your site(s). If you are a licensed user of GET and are ordering additional manuals or licenses, please enter your original serial or invoice number. Questions, comments, and suggestions are always welcome. Contact us at: MOBY DISK: 1021 San Carlos Road, Pebble Beach, CA 93953 Phone: (408) 646-1899 COMPUSERVE:72357,2276 America Online: MobyDisk2 Internet: bob.stephan@nitelog.com BBS: Nitelog 408-655-1096 BBS: The Cricket 408-373-3773 /s/ Bob Stephan May 29, 1995 GET 2.7 Table of Contents Page v Table of Contents READ.ME..................................................................iii LICENSING SUMMARY........................................................iii Vendors, Corporate, and Commercial Users...............................iii Individuals, Shareware Authors, and SYSOPS.............................iii AVAILABILITY..............................................................iv REGISTRATION and LICENSING................................................iv INTRODUCTION...............................................................1 SYSTEM REQUIREMENTS........................................................1 ACKNOWLEDGMENTS............................................................1 ABOUT THE AUTHOR...........................................................2 LIMITED WARRANTY (and other legalities)....................................2 COPYRIGHT DISPLAY..........................................................2 HELP SCREENS...............................................................3 SYNTAX EXPLANATIONS........................................................5 Command..................................................................5 Argument(s)..............................................................5 [] brackets............................................................5 "" double quotes.......................................................5 filespec...............................................................5 chars..................................................................5 num, div...............................................................5 $num.........................Hexadecimal Notation........................5 #..............................ASCII Numbers.............................6 Environment..............................................................6 ErrorLevel...............................................................6 Extended.................................................................6 Surrogates...............................................................6 Switches.................................................................7 Kilobytes................................................................7 ENTERING COMMANDS..........................................................7 DEBUGGING..................................................................8 SEE HOW IT RUNS............................................................8 ERRORLEVEL.................................................................9 SWITCHES AND SUCH.........................................................11 GLOBAL SWITCHES...........................................................11 /B.........................Flush Keyboard Buffer........................11 /H..............................Hex Output..............................11 /L...............................Lowercase..............................11 /M..........................Master Environment..........................11 /R...........................Numerical Result...........................11 /TR..............................Trim Right.............................12 /TL..............................Trim Left..............................12 /T.................................Trim.................................12 /U...............................Uppercase..............................12 /V.............................Variable Name............................12 LOCAL SWITCHES............................................................13 /A...........................Prompt Attribute...........................13 /C..........................Suppress Ctrl-Break.........................14 /E.............................Enhanced Keys............................14 /K...............................Kountdown..............................14 /N.................................No CR................................14 /S.............................Sound Control............................14 /W............................Wait or Number............................14 /X....................Extended Keys or eXtra function...................15 USING GET COMMANDS........................................................16 STRING HANDLING AND SCREEN I/O............................................16 Page vi Table of Contents GET 2.7 GET C...........................GET Character...........................20 GET N.........................GET yes/no aNswer.........................23 GET T............................Moving Text............................25 GET S.............................GET String............................27 GET I..........................Check Key Buffer.........................30 GET EC...............................Echo...............................32 GET Z..........................Put String (Zap).........................33 GET ZE..........................Standard Input..........................38 GET #..........................Locate Substring.........................40 GET R.............................'Rithmetic............................42 GET B........................Clear (Blank) Screen.......................46 GET V.........................Get/set video mode........................48 GET VE.......................Get/set video border.......................49 GET H...........................Date and Time...........................50 GET U..........................Keyboard BUffer..........................57 GET UE............................Shift Locks...........................59 GET DISK and FILE Information.............................................60 GET K........................Get disk free space........................62 GET Q.....................Get Disk Capacity (Quota).....................64 GET L..........................Get volume label.........................66 GET LE........................Match volume label........................68 GET F...........................Get file size...........................69 GET F /E..........................Get file date.........................74 GET FP...........................Get Full Path..........................76 GET X..........................Execute Program..........................78 GET XE............................GET's Path............................79 GET Y........................Drive and Directory........................80 GET YE.........................Logged/Boot Drive........................80 GET MEMORY and SYSTEM Information.........................................82 GET BR........................Get/Set Break Flag........................82 GET P.......................Check for Printer(PRN)......................84 GET PE......................Initialize Printer(PRN).....................84 GET E........................Get Environment Size.......................86 GET M..........................Get Memory Free..........................88 GET D..........................Get DOS Version..........................89 GET DV.........................DESQview Version.........................90 GET 7.........................Check Coprocessor.........................91 GET 7E..........................Check CPU Type..........................91 GET 4........................4DOS/Windows Status........................92 GET 4E.......................Check Windows Status.......................92 GET A.........................Check for ANSI.SYS........................94 GET AE.....................Check for ROM BIOS Model.....................94 GET W...........................Warm/Cold Boot..........................95 The Environment and Shells................................................96 Out of Environment Space..................................................96 PROGRAM INFORMATION.......................................................98 RUNTIME Version for Registered users......................................98 LICENSING AND DISTRIBUTION................................................98 Corporate Users.........................................................99 SYSOPs, User Groups, and Shareware authors..............................99 Vendors.................................................................99 Registered Users........................................................99 SPECIAL OFFER............................................................100 Appendix A.......................ASCII and Scan Codes......................A GET.EXE Bob Stephan's Batch File Enhancer Version 2.7 INTRODUCTION BATch programming can make your computing life easier. BATch programming with GET can make your BATch programming much easier and more productive. Most versions of DOS do not support a wide variety of useful features in the BATch programming commands that are available. GET supplements these commands, and gives BATch the capabilities it needs to really do a proper job as a macro language. GET provides additional commands in three general areas: String Handling and Screen I/O Commands Disk and File Commands Memory and System Commands The commands are fully described herein, along with some general information on BATch programming and the use of ErrorLevel and the DOS Environment. However, this is not a BATch programming tutorial or primer. Many useful books and publications can give you startup help if you need it. Among those that I am familiar with are books by Nick Anis and Craig Menefee, Ronny Richardson, and "DOS Power Tools." SYSTEM REQUIREMENTS GET is compatible with all computers running DR, MS or PC-DOS Versions 2.0 and later, although versions later than MS-DOS 3.1 or equivalent are preferred and some features require 5.0 or later. It is also compatible with OS/2 DOS emulation. It requires only about 15Kb of memory to run and is stored on disk in a compressed format that is about 7Kb. It is not memory resident (TSR) and will not reduce the amount of memory available to other programs. It supports all types of monitors and display adapters whether monochrome or color. To support the many features of GET it is preferable if you are running DOS 5.0 or later. A few of the features may not work on earlier versions, or with some of the early XT and AT ROM BIOS's. Where these limitations are known, they are mentioned in this document. GET Version 2.7 is distributed as GET27.EXE so as to not inadvertently overwrite previous versions. Rename GET27.EXE to GET.EXE when you are ready to replace older versions. If you have been using an older version of GET, read the file GET27NEW.DOC to find out what has been changed, and what has been added. ACKNOWLEDGMENTS My thanks to members of MBUG-PC, The Monterey Bay Users' Group - Personal Computer, for their support. Many members have used preliminary versions and offered their comments and suggestions. I am particularly grateful to the beta testers who held my feet to the fire to ensure that this would be a reliable and useful product. I am also grateful to the Bantam Computer Books for including GET in the Revised Second Edition of "DOS Power Tools," and to the authors Nick Anis, Craig Menefee, and Ronny Richardson for including GET in their books on batch files. Page 2 INTRODUCTION GET 2.7 ABOUT THE AUTHOR Bob Stephan has been using and programming computers for over 30 years, mostly for other companies and for his own use and enjoyment. Shareware is his first independent commercial venture. He has been a mainstay in his local computer users group for over 12 years and is a past president as well as an author of articles for the newsletter, a leader of special interest groups, and a provider of help to members on a variety of topics. LIMITED WARRANTY (and other legalities) Bob Stephan warrants the physical diskette and physical documentation provided with the registered version to be free of defects in materials and workmanship for a period of sixty days from the purchase date. The entire and exclusive liability and remedy for breach of this Limited Warranty shall be limited to replacement of the defective diskette or documentation and shall not include or extend to any claim for or right to recover any other damages, including but not limited to loss of profit, data, or use of the software, or special, incidental, or consequential damages or other similar claims. In no event will any liability for damages ever exceed the registration fee actually paid for the license to use the software, regardless of any form of the claim. Bob Stephan specifically disclaims all other warranties, express or implied, including but not limited to, any implied warranty of merchantability or fitness for a particular purpose. However, I claim that this software will perform substantially as detailed in this documentation when used on a machine with compatible software (DOS) and compatible firmware (ROM BIOS). If it does not work as documented when used in conformance with this documentation, I will either fix it if it is broken or refund your registration fee. If you are not satisfied, return the original registered disk and documentation within 30 days for a full refund of the registration fee paid. COPYRIGHT DISPLAY The shareware version of GET will display the copyright notice the first time it is invoked and periodically after that as it is used. GET checks the Environment block to determine whether it has been run prior to the current call. The g$$= variable (notice the lower case g) is created by GET to keep track of the number of times GET has been called. The registered runtime version does not display the copyright notice unless it is called with no valid arguments. The runtime version for registered users is under 6K in size. See additional information later in this document about the runtime version. GET 2.7 HELP SCREEN Page 3 HELP SCREENS If you enter GET alone, or with an invalid argument such as a question mark, it will display a summary of all GET commands. See SYNTAX EXPLANATIONS next for definitions of the notation used in the Help Screen. The help screens are displayed in three pages with a pause after each. You may exit at any pause by pressing {Esc}. If no key is pressed it will time out in 15 seconds and go to the next screen. Press Esc to exit at this point, or any key except space, CR, PgUp, or Esc to cancel the timeout. PgUp can be used to return to the first screen and start over. If you cancel the timeout with any key except space, CR, Esc or PgUp, you can later enter any of those keys to restart the display or perform the desired action. You can make a file copy of this Help Screen by using DOS redirection. Enter the command GET >GET.HLP. Each time you see the --More-- prompt, press Enter again. This Help Screen will be in the file GET.HLP. When you are BATch programming, put the help file in one of your editor's windows where you can use it for quick reference. For convenience a preformated copy of GET.HLP is included in the program package. The next page contains a printout of the complete help screen display as it was captured from the executable file. Page 4 HELP SCREEN GET 2.7 ╔══════════════════════════════════════════════════════════════════════════════╗ ║GET Version 2.7 - Bob Stephan's BATch Enhancer - Copyright 1995 Bob Stephan ║ ║ Syntax: GET command argument(s) /switches More Instructions: GET.DOC ║ ║Purpose Command Argument(s) Switches Environment ErrorLevel Extended ║ ║--------- ------- ----------- ---[/]-- --(GET=)--- --(Exit)-- --[E]--- ║ ║ --------- String Handling and Screen I/O Commands -------- ║ ║Echo EC "prompt" ANS -- -- -- ║ ║Get character C[E]["prompt"][chars] All ASCII Char ASCII code No Echo ║ ║aNswer yes or no N[E]["prompt"][seconds] All ASCII Char ASCII code No Echo ║ ║Get string S[E]["prompt"][pattern] All String Length Echo . ║ ║Put string (Zap) Z ["string/&var"][skip]AWX String Length -- ║ ║Standard Input ZE ["prompt"] [skip] AWX String Length -- ║ ║In String #[E] "string" ['arg'] WX Position in string Extract ║ ║Moving Text T[E] "filespec" [chars] EX ASCII Char ASCII code No Echo ║ ║Key waiting I[E]["prompt"] AEX --Character Waiting-- Get Char ║ ║Keyboard bUffer U[E]["chars"][num][/Wnum]W [E]Locks Length Caps/Num ║ ║ For UE: 16=Scroll Lock, 32=Num Lock, 64=Caps Lock ║ ║'Rithmetic R ["+-*/!=&#^~"] num [/Wnum] AW Result Result ║ ║Blank Screen B[E] [New attribute] AWX --Old attribute-- HexAttr ║ ║Video mode/bordr V[E] [New mode/color] --Old mode/color-- Border ║ ║Date and Time H[E] ["prompt"] code ACWXS Value Value ║ ║ Code:1=DoW 2=DoM 4=Mon 8=Yr 16=Hr 32=Min 64=Sec 128=odd/even 256=00ths 512=yy║ ║ --------- Disk and File Commands -------- ║ ║File size F[E] filespec[/Wdiv/X/A] AEWX Bytes/Hex Kilobytes Kb/10 ║ ║File date F[E] filespec /E/Wcode ACES Value Value ║ ║ /E required, /W codes: 2, 4, 8, 16, 32, 64, 512 as for GET H[E] ║ ║Full Path FP filespec Fullpath Length -- ║ ║Disk free space K[E] [drive] [/Wdiv] AWX Kilobytes Kb/10 Kb/100 ║ ║Disk capacity Q[E] [drive] [/Wdiv] AWX Kilobytes Kb/10 Kb/100 ║ ║Volume label L[E] ["label"][drive] X Label 1=yes,0=no Match ║ ║EXEC X[E] "d:\path\program.ext" 'args' Exit[Path] Exit[Drive] Path ║ ║Current dir Y [drive] Directory Level:Root=0 ║ ║Current drive YE (boot drive /X) Drive Drive:A=0 ║ ║ --------- Memory and System Commands -------- ║ ║Environment left E[E] (full size /X) Bytes Bytes Bytes/10 ║ ║Memory free M[E] Kilobytes Kilobytes Kb/10 ║ ║Break Flag BR [New flag 1=on, 0=off] Old flag -- ║ ║Printer(PRN) P[E] ["prompt"] [test] X 1=yes,0=no 1=yes,0=no Init ║ ║DOS Version D[E] Major Vers MajorMinor MinorEnv ║ ║DESQview Version DV Major Vers MajorMinor -- ║ ║4DOS Version 4 Major Vers MajorMinor -- ║ ║Windows 4E 1=yes,0=no 1=yes,0=no -- ║ ║Coprocessor/CPU 7[E] 1=yes,0=no 1=yes,0=no CPU Type ║ ║ANSI.SYS/Model A[E] 1=yes,0=no 1=yes,0=no PC Model ║ ║Warm/Cold Boot W[E] ["prompt"][arg] All If arg:1=warm, 0=cold ColdBoot ║ ║ Surrogates: }=Carriage Return, ~=Escape, Alt-255=Space/Blank. ║ ║ GLOBAL SWITCHES: (apply to most commands if appropriate) ║ ║ /H Hex output, /M Master Env, /R Return Code in Environment, /U /L case ║ ║ /B flush key Buffer, /TL/TR/T Trim Left/Right/Both, /V[&]var=, /V- No var ║ ║ LOCAL SWITCHES: (action depends on the command) ║ ║ /A[num] Attribute ["prompt"], All bytes [F], ASCII [R] /N No CR ║ ║ /K 10 second timeout Kountdown, /S[n] Sound control/Date format ║ ║ /C suppress Ctrl-Break during input [C,S,N], Compressed date [H,F/E] ║ ║ /E /X EXtended keys/EXtra feature, /W[num] Wait or numerical value ║ ║ See GET.DOC for additional features and BATch programming instructions. ║ ║ GET is a shareware product. Registration is required for continued use. ║ ╚══════════════════════════════════════════════════════════════════════════════╝ GET 2.7 SYNTAX EXPLANATIONS Page 5 SYNTAX EXPLANATIONS (Refer to the HELP SCREEN) Command: Commands are one or two character combinations as shown on the HELP SCREEN. Single character commands can [optionally] be immediately followed by E with no spaces between. The E indicates the Extended function in the last column on the HELP SCREEN. There must be only one space between the word GET and the command character. Argument(s): Arguments are zero, one, or two character strings as appropriate to the command. A "string" is a sequence of consecutive ASCII characters delimited by double quotes or, if not in quotes, by the space character. In some cases the first, or only, argument must be enclosed in double quotes as shown on the HELP SCREEN. Arguments that are not shown in quotes on the HELP SCREEN must not be put in quotes. Each character string can consist of zero or more ASCII characters. The blank or space character (ASCII 32) delimits the character strings that are not in quotes. The space character can only be a member of one of the strings that is enclosed in double quotes. (In this document, both "blank" and "space" are used as synonyms for the ASCII-32 character.) [] brackets indicate optional portions of commands and/or arguments. The command may work differently depending on whether these portions are included or not. The brackets themselves must not be included! " Where double quotes ("'s) are shown, they must be included if the corresponding prompt, string, or filespec argument is used. A "prompt" is a special case of a string that is displayed to prompt the user for input from the keyboard. filespecs consist of a filename and extension as appropriate to the DOS file naming conventions. They may include drive and path but no wildcards in the general form of d:\path\filename.ext. chars refers to an ASCII character string which can include any of the ASCII characters from decimal 33 to decimal 255 inclusive, but some of these characters have special significance (see the section on Surrogates below.) When a character argument (the arg not in double quotes) is called for, it can optionally be enclosed in single quotes ("'"s commonly used as apostrophes). To include a single quote in the argument, use two apostrophes next to each other. There must always be an even number of quote symbols. An argument consisting of just two single quotes ('' by itself) is the same as no argument at all. To specify exactly one quote and nothing else use ''''. Quoting permits including a space in the argument for GET C, for example. Since you cannot test for a space with IF, the space character will be reported as ASCII 255 unless the /L switch is used. The single quote is usually on the same key with the double quote character, and should not be confused with the grave accent or "back quote" character which is often on the same key as the tilde. num, div and other numerical arguments must be entered as ASCII decimal digit characters representing an integer no larger than 65,535 with no commas or decimal points. $num The $-sign prefex indicates that num is in Hexadecimal if a number Page 6 SYNTAX EXPLANATIONS GET 2.7 is expected. This is especially useful for GET R and GET B, and can be used any place a numerical arg or parameter is expected. #a The #-sign prefix to an ASCII character means use this character as a number. Thus you can perform arithmetic using the numerical value of ASCII characters, or simply use it to report the ASCII number for a character. The # character, like the $ character for hex, can be used wherever numerical input is expected; however, with the # character only one character immediately following it is converted to the ASCII value of that character. These conversions will be most useful with the GET R arithmetic functions. Environment: this column indicates what will be found in the Environment string GET= or the one you name with the /V switch. This string can be accessed from a BATch file with the %GET% notation. It is best to enclose %GET% in double quote characters in case it is empty. For example: IF "%GET%"=="" will check for an empty GET variable. The variable name can be changed with the /V switch described below. If you need more information on testing Environment variables, see the section on Environment and Shells later in this document. ErrorLevel: this column indicates what value will be placed in the DOS ErrorLevel where it can be accessed in BATch files with the "IF ErrorLevel" subcommand. Always check for ErrorLevel from highest to lowest values of interest. ErrorLevel is also referred to as Exit Code or Return Code. If you need more information on testing the ErrorLevel, see the next section on ERRORLEVEL. Extended: this column indicates the action taken if the optional E for [E]xtended command is included. The E must be immediately adjacent to the command, and do not include the brackets! In most cases E applies to either the result in the Environment or the result in the ErrorLevel, but not to both. In a few cases the E invokes a separate but loosely related function. Surrogates: Some characters are awkward or impossible to handle directly in BATch files. For example, BATch files generally use the carriage return <CR> and space characters as delimiters instead of as ASCII characters that can be manipulated. Some special symbols have been designated to facilitate the handling of these characters. These substitutions may have different meanings depending on the command being used, so read the description of the command. The special characters are: Carriage Return: } is used for CR Escape: ~ {tilde} is used for Esc Blank: {Alt-255} is used for Space (Blank). The Alt-255 character can be entered in most text editors by holding down the Alt key while spelling out the digits for the character on the number pad of the keyboard, but check your text editor for this capability. It is often convenient to ask the user to press the space bar for GET C. The blank (or space) surrogate, Alt-255, makes it possible to check for a space. In most versions of DOS the subcommand IF "%GET%"==" ", or any GET 2.7 SYNTAX EXPLANATIONS Page 7 comparison of strings which include spaces, does not work properly since DOS uses the space as a delimiter. By using Alt-255 as a surrogate for the space character, WYSIWYG is maintained, and the character can be manipulated like any alphabetic character. 4DOS, however, treats strings in double quotes properly. Switches are special modifiers to GET commands. A switch is indicated by the forward slash character, "/", immediately followed by the appropriate letter or character. See SWITCHES, page 11. Kilobytes (Kb) refers to the number 1024 which is 2^10 as commonly used in measuring digital computer memory and disk space. Some of GET's results (especially disk space) may differ from other measures that use kilo to refer to the number 1000. Similarly, a Megabyte (Mb) is taken to mean 1024Kb. Definitions that are sometimes used elsewhere are 1000Kb or 1,000,000 bytes. ENTERING COMMANDS GET is used in DOS BATch files. It has been tested with various versions of MS-DOS, PC-DOS, and 4DOS. When you want to use GET in a BATch file use the following simple procedure: 1. Enter the word GET as the first entry on a line, followed by a single space. 2. Tell GET what it is that you want it to get for you. Do this by selecting and entering a one or two letter command from the Command column on the HELP SCREEN. All of the commands are described in this document and the syntax notation of the Help Screen is explained in the SYNTAX section above. 3. If there are arguments, enter a space and then the arguments that you need or want to run the command. 4. If you want to use any of the /switches, enter them on the same line after all argument(s). 5. On the next line of the BATch file, check the return from GET in the ErrorLevel and/or the GET= variable in the Environment. The Environment variable can be accessed as %GET% or by the name you give it with the /V switch described below. For example, to get a yes or no answer you might enter the lines: :Ask GET N "Answer yes or no: " IF "%GET%"=="N" goto NO IF "%GET%"=="Y" goto YES Rem The next line checks to see if the user pressed Escape if ErrorLevel 126 goto END ECHO You must enter Y or N, or press Esc to exit. goto ASK :NO Rem [Do what you need to do if the user enters N] goto END :YES Page 8 ENTERING COMMANDS GET 2.7 Rem [Do what you need to do if the user enters Y] :END The next line clears GET out of the Environment. set GET= DEBUGGING GET includes a debugging feature to show you what it is doing and help you determine the cause of any problems you might be encountering in your BATch programming. To use the debugging feature, issue the SET GET?=ON command at the DOS prompt. This tells GET to report to the screen what information it is putting into the Environment and in the ErrorLevel. This feature is supported in both the shareware module and in the registered RUNTIME module. SEE HOW IT RUNS The best way to find out how GET works is to just try it. You can try it from the command line by using the special built-in reporting feature. To see what GET is putting in the ErrorLevel and the Environment, issue the DOS command SET GET?=ON. This will tell GET to report the results to the screen in addition to placing them in the ErrorLevel and the Environment. Then run the GET commands that you want to check out, or run your BATch file to see what GET reports. You can also try GET from the command line if you use SET (by itself) to check what has been placed in the Environment, but to find out what is in the ErrorLevel, you must use a BATch file unless you SET GET?=ON. If you are not familiar with the DOS Environment, see the discussion of Environment and Shells elsewhere in this documentation. GET 2.7 The Error Level Page 9 ERRORLEVEL If you are not familiar with testing for the ErrorLevel in BATch files, read this section. If the ErrorLevel holds no mysteries for you, then skip to the next section. To test a program to determine what ErrorLevel(s) it returns, use RUN.EXE included with GET. See RUN.DOC for details. Most modern programs that run under DOS issue a numeric status code which is passed back to DOS when they terminate. This is variously referred to as a "return code", "exit code", "status code", "error code", "Error Level", etc.. An "ErrorLevel" is simply that code, whatever it may be called. In many programs an ErrorLevel of 0 means a normal, successful completion, and a non-zero return code indicates a problem of some sort. GET uses the ErrorLevel for different purposes to pass information back to the BATch file in such a way that the BATch file can make use of it with the IF ERRORLEVEL subcommand. IF ERRORLEVEL is one of the cases of the IF statement. It tests the return code from the program for some condition that you specify. The various IF tests always result in a true/false result - either the test is true or it is false. If it is true, the statement following the IF test on the same line is executed, otherwise it is ignored. The IF ERRORLEVEL test is always a "greater than or equal" test, or in BASIC parlance >=. So when you enter IF ERRORLEVEL 5 DO SOMETHING, it means "if the return code from the previous program is greater than or equal to 5" the BATch file is to do something, otherwise it will ignore the rest of the line starting with IF. To test specifically for an ErrorLevel of 0 you use the NOT parameter for the IF subcommand. So when you enter IF NOT ERRORLEVEL 1 DO SOMETHING ELSE, it means "if the return code is not greater than or equal to 1 do something else." Since return codes can only be integers 0 through 255, a return code that is not >= 1, can only be 0, hence the test for ErrorLevel=0. ERRORLEVEL tests can be "and"ed to test for a specific return code. If you enter IF ERRORLEVEL 5 IF NOT ERRORLEVEL 6 DO STILL ANOTHER THING, it means "if the return code is greater than or equal to 5 but not greater than or equal to 6 do still another thing." The only integer that satisfies those conditions is 5 itself. Not all programs return error levels. DOS itself is the worst offender. No internal commands that I know of return codes, and not all the external commands are so thoughtful. Later versions of DOS are getting better about returning and documenting such codes, but unless it is documented that a code is returned and what it signifies, there is no way to assume that one is available. To find out what a return code means you must read the documentation for the program or command. If there is a possibility of several return codes, the IF ERRORLEVEL tests must be used in descending order because of the >= meaning. For example, the MS DOS 5.0 FORMAT command is documented to have the following "exit codes." 0 The format operation was successful. 3 The user pressed Ctrl-C to stop the process. Page 10 The Error Level GET 2.7 4 A fatal error occurred (any error other than 0, 3, or 5). 5 The user pressed N in response to the prompt "Proceed with Format(Y/N)?" to stop the process You can set up a BATch file to automate the FORMATTING process, then check to see if it was successful. A portion of your BATch file might look like this: :AGAIN FORMAT %1 %2 %3 if ErrorLevel 5 goto DONE if ErrorLevel 4 goto ERROR if ErrorLevel 3 goto ASK Rem If it wasn't one of the above, it has to be 0, Rem so go back to see if you want to do it again. goto AGAIN :ERROR Come here if a fatal error occurred - code=4. ECHO The FORMAT command failed! :ASK Come here if the ErrorLevel was 3 - user pressed Ctrl-C GET N "Do you want to try another disk?" if "%GET%"=="Y" goto AGAIN :DONE Echo The FORMAT operation has been completed! Echo Have a good day. GET 2.7 SWITCHES Page 11 SWITCHES AND SUCH Switches are special modifiers to GET commands. A switch is indicated by the forward slash character, "/", immediately followed by the appropriate letter or character. More than one switch may be used with a command, and all switches must come after any other arguments. Switches that are not applicable to a command will be ignored and not cause any harm if inadvertently included. Where the switches duplicate other features, the switch is the preferred method. The switches that have been implemented in Release 2.7 and subsequent are /A, /B, /C, /E, /H, /K, /L, /M, /N, /R, /S, /T, /TR, /TL, /U, /V, and /W. GLOBAL SWITCHES The switches /B, /H, /L, /M, /R, /T, /TR, /TL, /U, and /V have global meanings that remain the same for all commands for which the meaning of the switch makes sense. Global switches are omitted in the list of switches for a command to simplify the listing, but they can be used wherever applicable. Most of these switches directly affect the output that will be put into the ErrorLevel and/or the Environment. /B flush keyboard Buffer. Useful to flush any type-ahead keystrokes when asking for user input. /H provides a generalized Hexadecimal output capability. Whenever numerical output is expected in the Environment, /H will convert the output to Hexadecimal. For GET F, /X will still report the full filesize in hex even if the errorlevel is in kilobytes (/A not being used), while /H will report kilobytes in hex unless /A is being used. See GET F for details. /L specifies that the string that is written to the Environment is to be forced into lower case. Any ASCII-255 characters will be "lowercased" to the ASCII space character, but remember that strings with spaces in them will not test properly with the DOS BATch IF subcommand. Also: see /U for Uppercase. Example: GET SE "Enter your password: " /C /L /M tells GET to try to put the string in the master environment instead of the child environment. If the BATch file is being run from a secondary shell, GET will bypass the environment of the secondary command processor and look for the master environment. Without /M GET will put the result into the first command processor environment that it finds. /M can be used with any GET command. If you need more information about the different environment areas see the section on ENVIRONMENT AND SHELLS. Example: GET Z "Put this string in the master environment" /M NOTE: There is a slightly different meaning for the /M switch with GET Z if the "&var" feature is used. See the description of GET Z for more information. Caution: Finding the master environment is not a documented feature of DOS, and there is no guarantee that /M will work under all conditions. For example, don't expect it to work if the command processor is running in a DESQview window or under Windows, and it may cause the system to hang. If you need this capability, be sure to test it under all possible conditions before relying on it. /R will force the Return Code into the Environment for any GET command Page 12 SWITCHES GET 2.7 instead of the normal Environment result. See example under GET F. /TR and /TL trim blanks from the string that is written to the environment. Trim is useful with S, SE, Z, ZE, and HE. /TR or /T+ will trim blanks from the right or trailing end of the string, while /TL or /T- will trim blanks from the left or leading end of the string. Both switches may be used in the same command if desired, or the /T (Trim) switch by itself (not /TR or /TL) will trim both left and right. You can also use /TB to trim both. Trim will also trim Alt-255 characters (as upper case spaces). /U specifies that the string that is written to the Environment is to be forced into upper case (Caps). Any spaces will be "uppercased" to ASCII 255 so that the string can be tested with the BATch IF subcommand. /U is not necessary with the C, N, I, or T commands. Also: see /L for Lowercase. Example: GET SE "Enter your password: " /C /U /Vvar= lets you specify a name for the Environment variable to be used in place of "GET". This can eliminate some BATch file lines that would be used to save the GET variable under another name with the SET command. The name must be contiguous with the V in /V and should be terminated with the = sign. Although the '=' sign is optional, the name must be terminated in some way, and the '=' sign is the recommended method. However, any one of the following characters will serve as the terminating delimiter for the name: =, space, /, or carriage return (indicating the end of the command line or BATch file line). Lowercase letters will be coerced to uppercase before placing the name in the Environment. The following example will establish an Environment variable that will show up as DEMO= instead of the default name GET=. Example (old method): GET C "Enter the drive letter: " ABCD set DEMO=%GET% Example (new method): GET C "Enter the drive letter: " ABCD /vdemo= /V&var Create mixed case Environment variable names. When you use the /V switch to create a variable name, if the first character is an ampersand (&) the name will not be converted to uppercase. If you have any lowercase characters in the name, they will remain lowercase, thus you can use all lowercase or even mixed case. With the GET Z "&var" feature, you will be able to read these variables, but they will not be available to most other DOS programs. Whether creating or reading a variable with &var, the & is not taken to be part of the name; however, any additional embedded &'s will be used as part of the name. CAUTION: If you modify BATch files to take advantage of the convenience of the /V switch, be sure you adjust all references to the %GET% variable in subsequent statements to reflect the new variable name. /V- completely suppresses creating the Environment variable under any name. No changes to the Environment will be made. This is useful when the result is of no interest, or when all the information required can be obtained from the ErrorLevel. This may be useful at times when there is insufficient free space in the Environment, or when there is reluctance to create an Environment variable which might overwrite one that is already there. NOTE: A side effect of /V- is that SET GET?=ON will have no effect. Since GET 2.7 SWITCHES Page 13 the search of the Environment is being completely bypassed, GET cannot check for the GET? variable. LOCAL SWITCHES The remaining switches may have different meanings and uses which depend on the command being used, and as defined in the description of the command. They are described here as they pertain to commands in the next section, String Handling and Screen I/O, as they affect the prompts and other aspects of obtaining input from the user. In subsequent sections some of these switches will have different meanings, so it is necessary to carefully read the description of the command to determine the correct usage of the switches. /A lets you control the screen attribute of prompts. The prompts can be displayed in reverse video, or any of 254 color combinations that are available on color monitors. /A by itself causes the prompt to be displayed in reverse video. /Annn, where nnn is a number between 1 and 254 specifies the attribute to be used for the prompt. The following table explains how to construct the attribute. It is not necessary to have ANSI.SYS or any of its clones loaded to display prompts with attributes. The color codes are: 0 Black 2 Green 4 Red 6 Brown 1 Blue 3 Cyan 5 Magenta 7 White For the foreground color for the characters: 1. Select the color number from the above table. 2. For high intensity (bright or light), add 8. 3. For Blinking, add 128. Example: Blinking, high-intensity magenta is 5+8+128=141 For the background color: 1. Select the color number from the above table. 2. Multiply it by 16. 3. Add it to the foreground color. Example: Blinking, high-intensity magenta on white is 141+(7*16)=253 GET C "This is in blinking, high-intensity, magenta on white " /A253 With some systems there can be a minor problem if the user presses break when the prompt is displayed on the bottom line of the screen if using /A to color the prompt. In some cases the prompt color gets taken by DOS as the new color to use for scrolling the screen. If the /A switch is not included, the prompt will be displayed in such a manner that ANSI sequences can be used for screen control. The "prompt" will always be sent to the screen even if standard output is redirected with DOS redirection (>). Without /A the prompt can be as long as will fit on the DOS command or BATch line which is limited to 128 characters total. With /A, the prompt is limited to 79 characters. See also the GET EC command for a specific method of echoing strings to the screen. Note that commands which do not use a "prompt" may use /A for other purposes. See the individual command descriptions for additional Page 14 SWITCHES GET 2.7 information. /C tells GET to handle Ctrl-C and Ctrl-Break instead of letting DOS do it. See the GET USER INPUT section for additional details. Example: GET SE "Enter your password: " /C. /E specifies that keystrokes will be read from the Enhanced keyboard when getting user input with the C, N, I, and T commands. See also /X. Example: GET C "Enter F11 to continue: " Θ /E NOTES: Extended keys are those with no ASCII representation, such as the function and cursor keys. Enhanced keys are keys on the enhanced keyboard which do not appear on older keyboard layouts, such as F11 and F12. Commands that do not accept keyboard input may use /E for other purposes. /K controls the "Kountdown" in commands that are waiting for user input, and may be used for other purposes with commands that do not ask for user input. /N is a switch to suppress the carriage return after a prompt. This works with any command that issues a prompt, including ECho (GET EC). Use with caution. If the prompt is on the bottom line of the screen and the /A switch is being used, DOS may pick up the prompt attribute as the new screen attribute as it scrolls. Various video BIOS's may produce different results. /S SOUND BYTES. Either /S or /S0 will turn off the beeps for various alerts, such as striking an invalid key, or getting a time-out. Additional sound control features have been added for use with the /Sn switch. As before /S or /S0 will turn off error beeps. /S1 (the default) is normal beeping using the ASCII 7 BEL character. The n in /Sn can also take on values from 2 through 255 to produce various combinations of sounds. This is best explained using hexadecimal input as /S$xy where x and y can each be from 0 through F (but together must represent a number greater than 1). Each hex digit (1-F) will produce a tone approximately 1/2 second long. The larger the digit, the lower the tone. A digit of 0 will produce no tone, thus all combinations except /S$0, /S$00, /S$1, and /S$01 are valid (i.e., /S$2 or /S$02 through /S$FF are valid). Experiment to find the ones that are pleasing to your ear. The GET EC (ECho) command will take the /Sn switch and unconditionally echo the specified tones with or without a "prompt" specified. All other commands that can produce beeps do so in response to an error condition or a timeout. /W has different meanings for different commands, but it is always used to input a number for use by the command. When getting user keyboard input, /W is used to specify a number of seconds to wait. In other commands the number has other meanings and uses. See the description of the command for further details. /W (by itself) is defined to be the same as /W0. This has implications for functions such as C, S, N, W, and R. See GET R below. When numerical input is used for an argument or with /W, the numbers can be as large as 65535 but may not include commas or decimal points. NOTE: All waiting periods work properly in multitasking environments. The GET 2.7 SWITCHES Page 15 DOS "idle interrupt" is called to permit multitasking in these environments. /X provides eXtra functionality for a command. It has different meanings depending on the command being used. When getting keyboard input, /X specifies that extended keys will be accepted. /X is also used to specify hexadecimal output for the GET F (file size) command, and for other purposes with other commands. See GET F or the specific command for further details. When /X is specified for GET S, if the user presses Escape, the Escape surrogate will be the result, and if the user presses Return {Enter} before pressing any other keys, the CR surrogate will be the result. A timeout will produce a 0 (zero) result. If /X is not specified, all three of these user actions will produce a 0 result. Page 16 Get User Input GET 2.7 USING GET COMMANDS The description of GET commands is subdivided into the following sections: String Handling and Screen I/O DISK and FILE Information MEMORY and SYSTEM Information STRING HANDLING AND SCREEN I/O The commands C, N, T, S, I, EC, Z, #, R, B, V, H, and U pertain to obtaining keyboard input from the user, moving and modifying text strings, and getting and setting screen attributes. These commands take 0, 1, or 2 arguments as shown on the HELP SCREEN, and can make use of many of the switches. "prompt" refers to an arbitrary character string that will be displayed on the screen to coach the user as to what type of input is expected. If a prompt is used, it must be enclosed in double quotes. Prompts can be displayed in reverse video or in color with the /A switch. NOTE: The "prompt" can be used to issue printer and ANSI.SYS control escape sequences. It is more convenient to use GET to do this, than to make changes to the DOS PROMPT and have to reset PROMPT, especially if the BATch file is going to be run on various computer systems that may use different prompts. Do not use /A when you want ANSI.SYS or one of its clones to see the prompt. If any form of /A is specified, GET uses a different method of displaying the prompt which bypasses ANSI.SYS. Note also, that when /A is used, the maximum length of the prompt is 79 characters. Longer prompts will be truncated to 79 characters. Without /A the prompt can be longer, limited only by the maximum length of a BATch file line which in most versions of DOS is 128 characters. 'chars' are ASCII character strings which may include the space character if enclosed in quotes, and can include surrogates. If any chars are given, user input will be limited to the characters in the character string including those indicated by the surrogates. If no chars are given, any key stroke will be accepted. To indicate that a carriage return, Esc, or space is acceptable, include the appropriate surrogate character. CR and Esc will return 125 and 126 in the ErrorLevel respectively, and the surrogate character in the Environment. Space will return Alt-255 if the characters are converted to uppercase. Uppercase is automatic with C, N, I, and T, or when the /U switch is used. It can be defeated with the /L switch. Think of ASCII 255 as an upper-case Space for purposes of GET input. pattern is a special case of chars in which certain characters have special meanings. See the S command for detailed information. switches as they pertain to this section of the manual. The following provides additional details for a few of them. See the previous section for descriptions of the /A, and /N switches. NOTE: Since global switches are generally applicable to all commands, only the local switches are listed for each command. /E uses the BIOS function for the enhanced keyboard. This permits the GET 2.7 Get User Input Page 17 recognition of F11 and F12 as well as other enhanced and extended keyboard keys. /E should not be used unless you are sure that all users of your BATch file will be using enhanced keyboards because it absolutely does not work on machines with older BIOS's that do not recognize the enhanced keyboard interrupt. /X specifies that extended keys will be accepted. /X is used in the same manner as /E, but will not recognize F11, F12 or other Enhanced keys. Example: GET C "Enter F1 to continue: " ƒ /X If extended or enhanced keyboard characters are specified with /X or /E (you don't need both) the scan code plus 100 will be in the ErrorLevel and the corresponding upper ASCII character in the Environment. A table of keyboard scan codes is included in Appendix A which can be found in the file SCANCODE.DOC. The extended and enhanced scan codes are mapped to the upper ASCII table by adding 100 to the scan code. For example, the scan code for F1 is 59. If extended keys are allowed, the upper ASCII character 159, "ƒ", will limit extended keystrokes to just the F1 key. Scan codes of 28 through 150 are recognized as the upper ASCII surrogates 128 through 250. A table of scan and ASCII codes is included in the file SCANCODE.DOC. One method of entering the upper ASCII characters is by using the Alt-NumPad feature of DOS. There are some caveats that go along with this extended key scheme. 1. If you want extended and/or enhanced keys to be recognized, you must include the switch for those keys. The upper ASCII characters will not be recognized as surrogates for the extended keys unless the switch is included. 2. If you specify any individual keys at all, then you must specify all keys that you want to allow. The following will not do what appears to be intended: GET C "Press x or any function key: " x /X In this example, only the X key will be accepted even though the /X switch is included. A better example is: GET C "Press x or F1: " xƒ /X or equivalently but not preferred: GET C "Press x or F1: " xƒ{ 3. Also note that the mapping of extended keys for GET U is not the same as for GET C. /C (Break): The /C switch will suppress DOS Control-C and Ctrl-Break handling. For this purpose it applies only to the S, C, and N commands, but may be used for other features with other commands. Ctrl-Break handling works a bit differently according to whether you have specified a waiting time or not. If no timeout has been specified, Ctrl-Break will just cause a beep. If a timeout has been specified, and the first keystroke is Ctrl-Break, then GET will simulate a timeout with an ErrorLevel of 0, the same ErrorLevel you would check for to see if there was a timeout. If any character is entered, the timeout is cancelled, and Ctrl-Break is handled as if there is no timeout. For single character input, Ctrl-C will return the value and ASCII character 3 (Heart) if all characters are allowed (no chars string), or a beep if Page 18 Get User Input GET 2.7 specific chars are specified. This provides versatility in break handling, but some experimentation would be a good idea to become familiar with the methods. /W[nnnn] The number nnnn following /W will be used to establish the number of seconds to wait for the first key stroke to be entered. If timeout takes place with nothing entered, the ErrorLevel will be 0, and there will be no GET variable in the Environment. If /W is omitted, GET will wait forever. If a wrong key is pressed the timeout is cancelled. Example: GET C "Answer Yes or No: " YN /W20 will wait 20 seconds for a character to be entered. If none are entered in that time, GET will exit with 0. If a wrong character (not Y or N) is entered, GET will wait until a correct character is entered regardless of the time. The default if /W is omitted is interpreted to mean wait forever. /W0 or /W with no number indicates no wait. The prompt will be displayed, and GET will immediately exit with ErrorLevel 0. This is useful to "echo" text in reverse video or in color with the /A switch. If a character is ready in the keyboard buffer due to a type-ahead, GET C, T, and N will read that character. If it was a valid character for the command, it will be reported as a valid character for the command. /K is a new switch to activate a countdown during the last 10 seconds of waiting time for /Wnum. GET C[E] and GET S[E] with the /Wn and /K switches for a waiting time will count the last 10 seconds as 9, 8, ..., 0. This gives a 10 second warning that the waiting time is about to expire If an invalid key is pressed during the waiting time, a splat, '*', (asterisk) will be displayed which will remain until a valid key is pressed. /L will convert any uppercase Environment characters to lowercase. For get C, T, and N, the ErrorLevel will still represent the ASCII code for the uppercase character, and the Echo, if any, will be the uppercase character. /S SOUND bytes. See description of the /Sn switch above. General: The C, N, I, and S commands read characters using a BIOS call so they bypass Standard Input and most keyboard redefinition methods (macros). The T and ZE commands use a DOS call so work slightly differently. IMPORTANT: Please remember that the special ASCII characters '<', '>', and '|' are DOS redirection characters and you cannot use them as characters in BATch files. 4DOS also uses '^' and the grave accent (back quote) as special characters so they should not be used unless you know that no users of your BATch file will be running 4DOS or NDOS instead of COMMAND.COM. Single keystrokes for C, N or T are acted on without pressing Enter. (String input, of course, will require the user to press Enter.) When a character is entered by the user in response to C, N, or T, it is compared with the list of valid chars (if any). This validation of characters is not case sensitive. That is, if the user enters a lowercase letter it will be converted to uppercase and the chars will also be converted to uppercase if necessary before any validation GET 2.7 Get User Input Page 19 comparisons are made. When checking for string matching with the MS DOS BATch IF subcommand, remember that it is case sensitive. Different versions of DOS handle IF "string1"=="string2" somewhat differently, and there have been several "bugs" reported in one version or another. Try to test any such constructs under several DOS versions including DR DOS and 4DOS/NDOS if possible. In some versions the string cannot contain any spaces. The test under 4DOS is not case sensitive, and it can contain spaces if the strings are enclosed in double quotation marks. Only 4DOS does it right. INTERNATIONAL DATES AND TIMES SUPPORTED The date and time functions in GET (H and F) will now report the dates and times in the format specified by the country code that is currently in use. (See additional information under GET H below.) Page 20 GET Character GET C GET C Get Character Syntax: GET C[E] ["prompt"] ['chars'] [/switches] Input: "prompt" to be displayed. 'chars' to specify the acceptable characters that can be entered. Output: ErrorLevel - ASCII or surrogate scan code. Environment - character entered Switches: /A controls Attribute of prompt /C suppresses Ctrl-Break and Ctrl-C /E enables enhanced and extended keyboard keys /K Kountdown the final 10 seconds /N Suppress carriage return after prompt /S Sound bytes /X enables extended keyboard keys /Wnum Waits num seconds for input C is short for "Character". GET C obtains a single character from the user and does not wait for a carriage return <CR> to be pressed. As soon as the user presses a key, GET immediately evaluates the key that was pressed. The keystroke will be echoed to the screen to provide the user with feedback on the key that was pressed. If the keystroke is an alphabetic character (letter) it will be converted to uppercase if necessary, although the echo will be the actual letter typed in by the user. The storage of the letter in uppercase can be reversed with the /L switch for lowercase. GET CE is a special case in which the character is not echoed to the screen. This might be useful if the character represents a password or other secret symbol that must be held confidential and hidden from the eyes of casual observers, or if the character entered has no special significance as with the PAUSE command. In its simplest form, GET C, no prompt is issued and any keystroke except extended keys will be accepted. The BATch file will simply pause until a key is pressed. However, the user should be given some indication of what is expected, and the prompt provides a convenient means to do so. For example, you can emulate the DOS PAUSE subcommand with the following command. GET C "Press a key when ready . . ." This is more convenient than the PAUSE subcommand because the prompt can be anything you want it to be such as "Press a key when you want to continue . . .". As with the PAUSE command, it can be preceded in the BATch file with ECHO statements giving more information as to what the pause is for. It is also more useful with the /A switch to control the attribute, and/or the /W switch to control the pausing time. The optional argument [chars] is a single string of characters that limit the acceptable user input. Any other character entered will produce a beep, and GET will wait for another character. In addition to the common alphanumeric keyboard characters, special characters can be indicated as discussed above under Surrogates and Extended Characters. The space character can be included if the string is enclosed in single quotation marks (apostrophes). GET C GET Character Page 21 If the /C switch is included, the user will not be able to exit by pressing Ctrl-Break, and Ctrl-C will be treated like any other character; i.e. if any chars are specified, then Ctrl-C will not be allowed because it cannot be specified, but if no chars are specified then Ctrl-C will return ASCII 3. Ctrl-C is ASCII 3 and will be indicated by the number 3 in the ErrorLevel and the ASCII character for 3, the heart, in the Environment. EXAMPLES: 1. To issue a message and wait for a key to be pressed similar to the DOS PAUSE subcommand: ECHO Make sure your printer is turned on. GET C "Press a key when ready . . ." 2. To present a simple menu and let the user make a selection. The /C switch indicates suppression of the Control-Break keystroke. Neither Control-C nor Control-Break will be accepted. :MENU ECHO A Word Processor ECHO B Spreadsheet ECHO C Database GET C "Select A, B, or C: " ABC /C IF "%GET%"=="A" GOTO WP IF "%GET%"=="B" GOTO SS IF "%GET%"=="C" GOTO DB GOTO MENU :WP Rem Call your word processor here GOTO MENU :SS Rem Call your spread sheet here GOTO MENU :DB Rem Call your database manager here GOTO MENU 3. To illustrate the use of surrogates. The empty space between } and ~ is the ASCII 255 character entered with Alt-255, not the regular space character. The /W20 waits 20 seconds for a response. /A will cause the prompt to be displayed in reverse video. Page 22 GET Character GET C :START GET C "Press <CR>, space bar, or Esc: " } ~ /W20 /A IF ErrorLevel 255 GOTO SPACE IF ErrorLevel 126 GOTO ESCAPE IF ErrorLevel 125 GOTO RETURN GOTO START :SPACE Echo The space bar was pressed. GOTO END :ESCAPE Echo The Escape key was pressed. GOTO END :RETURN Echo The Enter key was pressed. :END 4. Same example as 3 using the Environment variable instead of the ErrorLevel. Note that " " is ASCII 255 in double quotes, not the regular space character. As above, the /W20 switch will wait for 20 seconds then continue, but since none of the valid characters will be in the %GET% variable, the next 3 lines will fall through and the GOTO START line will cause a loop back to :START for another 20 second wait. :START GET C "Press <CR>, space bar, or Esc: " } ~ /W20 IF "%GET%"==" " GOTO SPACE IF "%GET%"=="~" GOTO ESCAPE IF "%GET%"=="}" GOTO RETURN GOTO START :SPACE Echo The space bar was pressed. GOTO END :ESCAPE Echo The Escape key was pressed. GOTO END :RETURN Echo The Enter key was pressed. :END GET N GET yes/no aNswer Page 23 GET N Get yes/no aNswer Syntax: GET N[E] ["prompt"] [/switches] Input: "prompt" to be displayed. Output: ErrorLevel - ASCII or surrogate code. Environment - character Switches: /A controls Attribute of prompt /C suppresses Ctrl-Break and Ctrl-C /K Kountdown the final 10 seconds /N Suppress carriage return after prompt /S Sound bytes /Wnum Waits num seconds for input GET N is a special case of C that will accept only y, n, carriage return, or Esc. The Ctrl-C suppression and the number of seconds switches to wait may be specified, but no [chars] argument will be recognized. The syntax rules for GET C apply to GET N. The only purpose for GET N is just to make programming yes/no answers a bit simpler than using GET C and having to always specify the YN and surrogate characters. EXAMPLES: 1. The following two statements are functionally identical: GET N "Answer yes or no (y/n): " GET C "Answer yes or no (y/n): " YN}~ 2. Using ErrorLevel. 89 is the ASCII code for Y, 78 is the ASCII code for N, 125 is the code for the Carriage Return surrogate, and 126 for the Escape surrogate. This example also illustrates a method of using the Environment for defining variables where the value of GET is redefined according to what the ErrorLevel was from the Yes/No question. The resulting value of %GET% is used in the message Echoed in the last line. GET N "Answer yes or no (y/n): " IF ErrorLevel 126 GOTO ESCAPE IF ErrorLevel 125 GOTO RETURN IF ErrorLevel 89 GOTO YES IF ErrorLevel 78 GOTO NO SET GET=Break GOTO END :ESCAPE SET GET=Escape GOTO END :RETURN SET GET=Return GOTO END :YES :NO :END Echo The %GET% key was pressed. 3. Same example as 2. This time the Environment is used instead of the ErrorLevel. Since we are not using Control-C suppression, it is possible to break out of the BATch file with Control-C or Control-Break in this and the previous example. Remember that in many versions of DOS Page 24 GET yes/no aNswer GET N the IF subcommand is case sensitive. GET N converts all alphabetic characters to uppercase, so always use uppercase comparison unless you are using the /L switch. GET N "Answer yes or no (y/n): " IF "%GET%"=="~" GOTO ESCAPE IF "%GET%"=="}" GOTO RETURN IF "%GET%"=="Y" GOTO YES IF "%GET%"=="N" GOTO NO SET GET=Break GOTO END :ESCAPE SET GET=Escape GOTO END :RETURN SET GET=Return GOTO END :YES Put your code for Yes on lines after this label. GOTO END :NO Put your code for No on lines after this label. :END Echo The %GET% key was pressed. GET T Moving Text Page 25 GET T Moving Text Syntax: GET T[E] "filespec" ['chars'] [/switches] Input: file specification containing moving text to be displayed. chars to specify the acceptable characters that can be entered. Output: ErrorLevel - ASCII or surrogate scan code. Environment - character Switches: /E enables enhanced and extended keyboard keys /X enables extended keyboard keys GET T is another special case of GET C which provides a special effect. The prompt information is presented as a moving line of text across the bottom of the screen. This permits having prompt strings up to 4096 characters long, and the motion of the characters helps to catch the users attention. T requires a file with the prompt string which will be displayed moving across the bottom line of the screen. Currently only standard 25 line screens are supported. The text file should be plain ASCII without any control characters (No CR, LF, or any other characters below ASCII 32). To be effective the prompt must be over 80 or more characters long, and to ensure smooth wrap-around the first 79 characters should be repeated at the end. The maximum length for the text of the moving prompt is 4096 characters. Over that it will be truncated. T does not accept a number of seconds-to-wait argument at this time so it will wait until a valid key is pressed. The T command can fail with an "Invalid Command" message if the file is not properly specified and cannot be found, or if the prompt string is less than 80 characters. An ErrorLevel of zero should be tested to determine if the command was successful (see example 2 below). A prompt string of exactly 80 characters will remain stationary. The question has been asked as to how to go about creating such a long prompt string without carriage returns or other control characters. Many text editors have the capability to do this by turning off word wrap. A good text editor will let you do just about anything you want to do with `ASCII text. Most programmers use a text editor instead of a word processor while creating and editing their code. Many word processors will let you use them as text editors by specifying "non- document" mode as appropriate. As with many things related to programming, trial and error experimentation is often the order of the day. Sometimes it is called "hacking". EXAMPLES: 1. If there is a file on the GET disk named SAMPLE.TXT, enter the following command to see the moving text effect: GET T "SAMPLE.TXT" 2. Example 2 for GET C can easily be modified to use a moving text prompt by changing GET C to GET T and replacing the prompt with the filename as follows. The timeout option is not effective with GET T. Page 26 Moving Text GET T :START GET T "sample.txt" } ~ IF NOT ErrorLevel 1 GOTO END IF ErrorLevel 255 GOTO SPACE IF ErrorLevel 126 GOTO ESCAPE IF ErrorLevel 125 GOTO RETURN GOTO START :SPACE Echo The space bar was pressed. GOTO END :ESCAPE Echo The Escape key was pressed. GOTO END :RETURN Echo The Enter key was pressed. :END In this example note the addition of the line IF NOT ErrorLevel 1 GOTO END. If the named file is not found due to not being in the current directory, or not having the correct path or name specified, then GET will report "Invalid Command" and exit with ErrorLevel 0. The added statement is a check for ErrorLevel equal 0, and should always be included when using the GET T command. You may include drive and path with the filename, but GET must be able to find it where it is specified to be. GET S GET String Page 27 GET S Get String Syntax: GET S[E] ["prompt"] ['pattern'] [/switches] Input: "prompt" to be displayed. 'pattern' to control character entry Output: ErrorLevel - length of string entered. Environment - string. Switches: /A controls Attribute of prompt /C suppresses Ctrl-Break and Ctrl-C /E enables enhanced and extended keyboard keys /K Kountdown the final 10 seconds /N Suppress carriage return after prompt /S Sound bytes /X enables extended keyboard keys /Wnum Waits num seconds for input S accepts character string input terminated by a carriage return. SE is the same but does not echo user input to the screen. Instead it echoes dots (...) to indicate the number of characters entered without compromising the actual entry. The latter is useful for hiding the entry of a password, for example. Extended and enhanced keys will not be accepted, but break can be suppressed with /C. The length of the string entered is returned in ErrorLevel. If the user presses Esc, GET will exit with 0 in ErrorLevel as if a timeout has occurred unless the /X switch is specified as described below. As with GET C, the prompt will be issued and then GET will wait with the cursor on the same line as the prompt for keyboard input. If a /W is specified, GET will wait the specified number of seconds for the first key to be pressed, then exit with an ErrorLevel of 0 if no key has been pressed. If any key is pressed during the waiting period, the wait is cancelled and GET waits for the user to press the Carriage Return (Enter) key. When /X is specified, if the user presses Escape, the Escape surrogate will be the result, and if the user presses Return (Enter) before pressing any other keys, the CR surrogate will be the result. A timeout will produce a 0 (zero) result. If /X is not specified, all three of these user actions will produce a 0 result. GET S /C now also disables the Esc key as well as Ctrl-C/Break, but only if the /X switch is not included. With /X the Esc key exit can easily be detected and appropriate action taken so disabling does not seem necessary. The old /~ switch for GET S has been completely eliminated. /E turns on function keys as Exit keys. If the user presses a function key (F1-F10 only), and if /E is specified, then the surrogate code (100+scan code) for that function key will be reported. /E includes /X, so both are not needed. /E does not turn on Enhanced keys in this case, it only enables F1-F10. This permits something like "F1 for help" to be used. The input buffer for GET S[E] and GET Z[E] is 255 characters. This allows longer strings to be input, especially for GET Z and GET ZE where the input might be from redirection or from an Environment variable. The max length of the BATch command line, including substitution of Page 28 GET String GET S Environment variables is still limited by DOS to 128 characters - can't change that. Additional sound control features added for use with the /Sn switch. See the description of the /S switch above. The length of a string for the S command can be controlled by creating a pattern of characters equal in number to the maximum length of the string allowed. If the argument is omitted the default is 255 characters. A beep will be sounded if the maximum length has been reached and more characters are attempted, or if any characters do not match the specified pattern. The maximum length of the input string for GET S is 255 characters. The pattern in the argument specifies the acceptable characters for each position as follows. Note that the uppercase characters T, A, and Z will cause lowercase characters to be converted to uppercase. Conversions to uppercase will also cause the space character to be converted to ASCII 255. This will facilitate BATch file checking with the IF subcommand. tT - any typeable character, T - a-z will be uppercased. aA - any alphabetic character, A - a-z will be uppercased. zZ - any alphanumeric character, Z - a-z will be uppercased. 9 - any digit 0-9. Alt-255 - space character only. Any other character must match the character entered exactly. In a sense you can think of Alt-255 as an uppercase space character. Remember that the regular ASCII space is used as a delimiter so the scanning of the pattern stops if an embedded space is encountered. If you need to specify the space, use the surrogate Alt-255, otherwise use t or T if a space is permitted. If you are going to test the input with the DOS IF subcommand use Alt-255 or T. This will cause the space to be converted to an Alt-255 which can be tested. Unless you are using 4DOS, if you try to test a string which contains a space with IF, you will get the message "Bad command or file name", even with MS DOS 5.0. This is because COMMAND.COM stops parsing the string when it encounters a space which it considers to be a delimiter even if it is enclosed in quotes. EXAMPLES: 1. The following example lets the user type in any characters up to a limit of 255. The string that is typed in will be in the Environment, and the length of the string in the ErrorLevel. Because the /X switch is used, if the user presses Esc, the Escape surrogate "~" will be in the Environment and 126 in the ErrorLevel. If the user presses Ctrl-C or Ctrl-Break, DOS will break out of GET with no change to the GET variable in the environment, and an undefined value in the ErrorLevel, possibly 3 for Ctrl-C. For this reason it is a good idea to clear the GET variable with the statement SET GET= before issuing the GET S command, or use /C to suppress Ctrl-Break as in the next example. The /U switch causes lowercase characters in the string to be converted to uppercase to facilitate IF tests. GET S /X /U 2. This example asks the user for a password. It does not echo the entry GET S GET String Page 29 to the screen to keep the password secure from prying eyes. It suppresses Ctrl-Break but allows the BATch file to check to see if the user entered Escape. The password is limited to 8 alphabetic or numeric characters, and all alpha characters will be converted to uppercase to facilitate testing. The /a switch causes the error message to be displayed in reverse video, and the /w switch causes GET to immediately exit after displaying the prompt. :START GET SE "Enter your password: " ZZZZZZZZ /C /X if "%GET%"=="~" goto Escape if "%GET%"=="PASSWORD" goto PWOK Rem Display error message in reverse video GET C "Incorrect Password" /a /w goto START :Escape GET N "Do you want to cancel your logon? " if NOT "%GET%"=="Y" goto START Echo Your logon is cancelled. goto EXIT :PWOK Echo Your logon has been accepted Rem Do whatever is necessary here to complete the logon. :EXIT 3. The next example gives the user 30 seconds to respond. If there is no first name entered within 30 seconds, GET will beep and the BATch file will cycle back to :START and ask the question again. If there is a timeout on last name, the BATch file will report that the session is cancelled and exit. Only alphabetic characters are allowed, and the first character will be automatically capitalized. :START GET S "Enter your first name " Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa /W30 if NOT ErrorLevel 1 goto START SET FIRST=%GET% GET S "Enter your last name " Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa /W30 if errorlevel 1 goto NAME Echo Your session is cancelled. Rem Do whatever is necessary to cancel session here. goto EXIT :NAME Echo Your name is %FIRST% %GET% :EXIT Page 30 Check Key Buffer GET I GET I Check Key Buffer» Syntax: GET I[E] "prompt" [/switches] Input: "prompt" to be displayed. Output: ErrorLevel - ASCII or surrogate scan code. Environment - character Switches: /A controls Attribute of prompt /E enables enhanced and extended keyboard keys /X enables extended keyboard keys I checks to see whether a key has been pressed but it does not wait for a keystroke if none is in the buffer; i.e. if the user has not pressed a key in type-ahead mode. The character that is waiting will be reported in the same manner as for GET C, but it will remain in the keyboard buffer. If there is no character waiting, the ErrorLevel will be 0 and GET or the variable specified with /V will be expunged from the Environment. IE will read the key if it is present and report it in the same manner as C, or return 0 and expunge GET from the Environment if no character is waiting. The difference in the IE command from the C command is that IE does not wait if no key is waiting. If you specify a zero waiting time for GET C with GET C /W or GET C /W0 it will be functionally equivalent to GET IE. You can control whether Extended or Enhanced keys are to be included in the same manner as for GET C. A prompt can be included and will be displayed, which makes I useful to "echo" text to the screen like the DOS ECHO command, but with GET you can specify reverse video or color attributes. But see GET EC below for a better Echo command. One way to make use of GET I is to allow a key to be pressed during boot- up (or while any BATch file is running for that matter), then check to see if a key has been pressed and take action accordingly, but if no key was pressed there will be no delay. Another use would be in a BATch program that the user is familiar enough with that s/he may anticipate the next question. GET I could be used to check to see if the user has answered the question before it was asked. EXAMPLES: 1. In these examples a GET command (GET U), explained elsewhere, is used to place a key in the keyboard buffer, then GET I checks to see if it is there. In this first example, the letter "a" is placed in the buffer and GET I reports that "A" is waiting with ErrorLevel 65 and GET=A. The character "a" will remain in the buffer and will be available to the next program that reads keyboard input. In this case, neither extended nor enhanced keys will be seen. GET I Check Key Buffer Page 31 Rem Simulate user pressing the "a" key. GET U "a" Rem Check to see if the key is in the buffer. GET I if ErrorLevel 1 goto ISTHERE Echo There is no key in the buffer. goto EXIT :ISTHERE Echo The key in the buffer is %GET%. :EXIT Rem Note that if you run this BATch file from the command line, you will Rem see "a" at the next DOS prompt when DOS reads the keyboard buffer. 2. Clearing the keyboard buffer. By using the switch /E, both extended and enhanced keys will be seen as well as all standard keys. Do not use /E unless you know that all users will have enhanced keyboards. Note: This example is for illustration only. A faster method of clearing the buffer is to use the /B switch. :LOOP GET IE /E if ErrorLevel 1 goto LOOP 3. Suppose you would like to be able to do a clean boot without any TSR's when you want to run a program such as a disk defragmenter. You can have GET I check if you have pressed a key, and skip your TSR's in your AUTOEXEC.BAT if you have. GET IE if ErrorLevel 1 goto CONTINUE Rem Load first TSR here. Rem Load Second TSR here. Rem ... Rem Load Last TSR here. :CONTINUE with the rest of your AUTOEXEC.BAT Page 32 Echo GET EC GET EC Echo Syntax: GET EC "string" [/switches] Input: "string" to be Echoed. Output: ErrorLevel - nothing Environment - nothing Switches: /A controls Attribute of prompt /N No carriage return after prompt /S Sound bytes GET EC provides a more versatile alternative to the DOS ECHO command. The attribute of the echo can be controlled with the /A switch, and the ending carriage return can be suppressed with the /N switch. The advantages to using this instead of GET I "Hello" is that no ErrorLevel or Environment information is generated and the ending carriage return can be suppressed with /N. If you want to Echo a printer command, for example, you can do it with GET EC "Esc command">PRN /N. An ANSI.SYS command can be echoed with GET EC "Esc command" /N. This is much more convenient than fooling around with the PROMPT command. GET EC will take the /Sn switch described above and unconditionally echo the specified tones with or without a "prompt" specified. All other commands that can produce beeps do so in response to an error condition or a timeout. GET Z Put String (Zap) Page 33 GET Z Put String (Zap) Syntax: GET Z "string" [skip] [/switches] GET Z "&var" [skip] [/switches] Input: "string" to be placed in the Environment Output: ErrorLevel - length of string. Environment - string Switches: /A with /W1 puts ASCII value of character in Environment /Wnum maximum length of string to transfer /X starts the skip operation from right to left. See GET ZE. Z uses the "string" as input. It will put the string into the Environment as the value of the GET= or /Vvar= variable. If you include the /M switch, GET will attempt to bypass any secondary environments and put the string in the master Environment. By "master Environment" is meant the environment of the original command processor that was loaded when you started your computer, as contrasted with what we shall call the "current" Environment defined as that of the command processor that is running the BATch file. The current Environment will be the same as the master Environment unless a secondary command processor has been invoked. If GET is running under a secondary command processor, GET Z with /M will attempt to bypass the current Environment of the secondary command processor and find the master environment. In the latter case, the GET variable will not be available to the current BATch file. See discussion of Environment and Shells. The maximum length of the input string for GET Z and GET ZE is 255 characters. This allows longer strings to be input, especially for GET Z and GET ZE where the input might be from redirection or from an Environment variable. The max length of the BATch command line, including substitution of Environment variables is still limited by DOS to 128 characters - can't change that. With GET you can, for example, put a PATH longer than 128 characters into the Environment. While it is not recommended, it is possible. One way to do it with GET is to put your desired long PATH into a one-line text file ending in a carriage return, then read it in with GET. For example, if your long PATH is in the file LONGPATH.TXT you can use GET ZE /VPATH= <LONGPATH.TXT >NUL By redirecting the output with >NUL you suppress the echo that is produced by DOS when reading the file. If a numerical [skip] argument is specified, it will be taken to specify the number of characters to skip over before transferring the remainder of the string to the environment. The /W switch can be used to specify the maximum length of the string as described for GET ZE below. Thus, GET Z can be used to extract a substring from "string" starting with the character after skip and using up to the number of characters specified by /Wnnnn. If [skip] is omitted the default is 0 meaning to start at the beginning of the string. NOTE: The use of /W with GET Z and GET ZE is different from the use with other input commands where it denotes a time to wait for input. GET Z can have several uses. A few that come to mind are: uppercase a Page 34 Put String (Zap) GET Z string to test it with the IF subcommand, measure the length of a string, count the number of times through a loop by measuring the length of a string that has a character concatenated on each pass, fill out a string to a fixed length by concatenating blanks and measuring its length, extract a substring from a string. If you use GET Z with /W1 to extract a single character, the ASCII decimal value of the character will be in the ErrorLevel (or 0 if the extraction failed). Previously GET dutifully reported an ErrorLevel of 1 meaning that you extracted one character, but you already knew that so it wasn't very useful. Reporting the value of the character provides additional information, and may save another call to GET to make that determination. Furthermore, for GET Z only, if both /W1 and /A (for ASCII) are specified, the ASCII decimal value will be spelled out in the Environment also. This allows it to be available to another BATch command, or another GET command such as GET R. If the extraction fails such as because the string is empty, or you skip too far, then the Environment variable will still be expunged. GET Z "&var" Using "&var" in the "prompt" argument for GET Z, where 'var' is the name of an Environment variable, will read the named variable value directly from the environment without using DOS to substitute the value for the name. When read this way the variable name is case sensitive so must be entered exactly as desired. NOTE: DOS will not substitute variable values on the command line. The %VAR% notation only works in BATch files. However, the GET Z "&VAR" command will work just as well on the command line as it does in a BATch file. (4DOS will make the %VAR% substitution on the command line.) This is an intriguing addition to GET which may have some interesting applications. Consider the following BATch file: for %%a in (1 2 3) do set var%%a=%%a for %%a in (1 2 3) do echo %VAR%%a% In general the echo in the second line will not echo the contents of VAR1, VAR2, and VAR3 because DOS does not recursively parse such a statement. I.e. after DOS substitutes for %%a to get %VAR1%, it does not again parse the line to get the value of VAR1. We could try several different variations of this theme, including calling a subroutine BATch file, but in general DOS will not parse the lines in the way that we would like it to. Note that we can write it so that 4DOS will parse it correctly, and by a convoluted method DOS can be tricked into doing it, but it requires echoing statements out to a temporary BATch file, and executing the temporary file. However, now we can do it more easily with GET. The new feature permits GET to read variables directly from the Environment, given the variable name. The above statements can then be written as follows to achieve the desired result: GET Z Put String (Zap) Page 35 for %%a in (1 2 3) do set var%%a=%%a for %%a in (1 2 3) do call echoget %%a ECHOGET.BAT as called is: get z "&VAR%1" Echo %GET% Note the ampersand in GET Z "&VAR%1". New for GET Z is if the first character of the string is an '&', the remainder of the string will be interpreted as the name of an Environment variable to be read into GET's Environment variable - either GET or /Vvar=. As seen in the example this permits a pseudo indexing of variables; e.g. VAR1, VAR2, VAR3, etc. The value of each can be set into the GET variable to be operated on by generic BATch statements. The GET R function could be used to increment the index, for example. Suppose you want to operate on a list of files. The file names could be loaded into the environment by SETting FILE1=filename1, FILE2=filename2, etc. These names can be extracted by GET Z "&VAR", maybe something like this: @Echo off Rem Create a temporary auxiliary file: Echo GET R %%N%% /W1 /VN= >LISTFILE.BAT Echo GET Z "%%1" /VFILE%%N%%=>>LISTFILE.BAT set N=0 Rem The next line puts the names of all the BAT files Rem into the Environment as FILE1, FILE2, etc. For %%a in (*.bat) do call listfile %%a del listfile.bat set J=0 Rem Now for DEMO purposes, list out the file names. Rem They could just as easily be operated on in some way. :LOOP GET R %J% /W1 /VJ= GET Z "&FILE%J%" Echo File %J% is %GET% set FILE%J%= IF NOT "%J%"=="%N%" GOTO LOOP set N= set J= set GET= Another advantage of this enhancement is that long variable values can be transferred, which might otherwise cause the BATch command line to be longer than 128 bytes if DOS does the substitution; for example a long PATH string. The usual skip arg and /Wmax switch can then be used to operate on these longer strings. To accommodate longer strings, the input buffer has been expanded to 255 characters. When the /M (for Master Environment) switch is used with GET Z "&var", GET will look for the variable in the Master Environment, and if the string is found will store it in the local Environment (which may be the same if there is no secondary command processor, of course.) This is a different use of the /M switch from other commands, and it provides a means to retrieve a string which was stored in the master environment. Page 36 Put String (Zap) GET Z Finally, the &var feature is case sensitive. Most Environment variable names are in upper case. A notable exception is the 'windir' variable that Microsoft Windows places in the Environment of DOS sessions. GET Z "&windir" will retrieve this variable if it is needed for some reason; however, this means the BATch programmer must take care to put other BATch Environment variable names in upper case for the &VAR feature. MORE EXAMPLES: 1. Place a string in the master Environment. The master Environment will then contain "GET=This is the string" and the ErrorLevel will be the length of the string (18). To verify that the string was placed in the master Environment, first run a secondary command processor by typing COMMAND at the DOS prompt. Then run this example and see that the string is not in the current environment by entering SET and viewing the Environment. Finally, enter EXIT to return to the original command processor and enter SET again to see that the string is actually in the master Environment. GET Z "This is the string" /M 2. Suppose you want to fill out a string with blanks to reach a certain fixed length. In this example let the fixed length be 16. This is one way to implement a loop and control the number of times the loop occurs. You can either right justify or left justify, and you can append spaces, unlike using the DOS SET command. Rem Get user input, maximum of 16 characters. get s "Enter name: " tttttttttttttttt /a :FILL If less than 16 characters entered, fill with blanks. if ErrorLevel 16 goto LENOK Rem Append a blank and loop back to check if enough get z "%GET% " goto FILL :LENOK Now we have the length we want. Echo "The string is %GET%" 3. Use GET Z to extract the 3rd, 4th, and 5th characters from a string. Rem Turn on GET's reporting feature SET GET?=ON GET Z "abcdef" 2 /w3 Environment: cde ErrorLevel: 3 4. Suppose there is an Environment variable named VER and that in this case it has the value VER=3.31. We can extract the DOS minor version with GET Z as follows. GET Z "%VER%" 2 Environment: 31 ErrorLevel: 2 5. Use GET Z to make sure an environment string is in uppercase to facilitate testing it with the BATch IF subcommand. Spaces will be converted to ASCII-255 otherwise the DOS IF test would fail. Remember GET Z Put String (Zap) Page 37 to use ASCII-255 for the test in your BATch file if there are any spaces. Let "varname" be the name of a variable in the Environment. GET Z "%varname%" /U /Vvarname= Rem In the next line, the "space" between B and S is really ASCII-255. IF "%varname%"=="BOB STEPHAN" goto NAMEOK Echo The name did not match goto END :NAMEOK Echo The name matched :END Page 38 Standard Input GET ZE GET ZE Standard Input Syntax: GET ZE "prompt" skip [/switches] Input: "prompt" to be displayed. Output: ErrorLevel - length of string. Environment - string. Switches: /A with /W1 puts ASCII value of character in Environment /Wnum maximum length of string to transfer /X starts the skip operation from right to left. ZE will take input from Standard Input and transfer it to the GET= or /Vvar= variable in the Environment. The input must be less than 128 characters and must be terminated with a carriage return. ZE will take input from the keyboard, or from redirection or piping. If you specify a prompt for ZE, it will be displayed before reading standard input. GET ZE works similar to GET S, but uses DOS to obtain the input string from the user; therefore, it is not able to monitor each keystroke and will not be able to suppress Ctrl-Break with the /C switch. You can force the string to uppercase with the /U switch, or to lowercase with the /L switch. /W can be used with both GET Z and GET ZE to specify the maximum length of the string. If the input string is longer than the maximum specified with /W, it will be truncated to the length specified. The <skip> argument works for GET ZE as well as GET Z. In order to extract anything when using /X there must be a skip argument. With /X the skip arg skips from right to left, and the /Wn takes n chars from that position to the RIGHT. If the /Wn is omitted, everything to the right of the starting position set by skip will be extracted. GET ZE works the same as GET Z except for the source of the string. Z takes the string from the "string" arg, and GET ZE takes the string from standard input. NOTE: You can save the length of a string as an environment variable with GET # above, or with GET Z with /R (see above). If you use GET Z or ZE with /W1 to extract a single character, the ASCII decimal value of the character will be in the ErrorLevel (or 0 if the extraction failed). Previously GET dutifully reported an ErrorLevel of 1 meaning that you extracted one character, but you already knew that so it wasn't very useful. Reporting the value of the character provides additional information, and may save another call to GET to make that determination. Note that for GET ZE the /A switch has its usual meaning of coloring the prompt. EXAMPLES: 1. GET S uses the BIOS interrupt to get characters from the user, but you can also use DOS Standard Input with GET ZE. The prompt will be displayed and the string can be entered from the keyboard for a maximum of 255 characters. The /U switch can be used to force the environment variable to uppercase, but the user will see it just as it was typed in. GET ZE "Enter a string: " /U GET ZE Standard Input Page 39 2. You can use GET ZE to pipe the current directory into the current Environment by using DOS piping. This could be used to redirect any standard output into an Environment variable. Of course, GET Y is the preferred method of putting the current directory into the Environment with GET, but this illustrates the method to do it with any program that writes to standard output. In some cases piping CD into GET ZE might be preferable because CD includes the drive specification. CD|GET ZE Environment: D:\QPRO ErrorLevel: 7 3. You can read the first line of a text file. If you don't want to see the echo from DOS, redirect the output to NUL. The general syntax is GET ZE<filespec>NUL. In this example, the output from the DOS DATE command is redirected to a file, then read in to the Environment with GET ZE, and finally the day of the week is extracted with GET Z. NOTE: The date could also have been piped directly into GET as in the previous example, but for the purposes of this example an intermediate file is used. Rem Stack <return> to automate the DATE command. get u 13 Rem Use the DOS DATE command to create a file for the date date >date.txt Rem The first line of the file will have the format Rem Current date is Sun 11-17-1991 Rem Read the first line into the variable GET=. get ze <date.txt Rem Extract the day of the week in characters 17-19 get z "%GET%" 16 /w3 Rem The Environment will now contain the variable GET=Sun. Rem Rem NOTE: Different versions of DOS have different formats Rem for the output of the DATE command. Rem Rem Now erase the temporary file. del date.txt 4. Extract the minutes and seconds from the DOS TIME command. GET U 13 TIME >TIME.DOS GET ZE 22 /W5 <TIME.DOS >NUL NOTE: This is not a reliable method if any users might be using DR DOS or 4DOS which have a different format for TIME and DATE. Page 40 Locate Substring GET # GET # Locate a Substring in a String Syntax: GET #[E] "string" 'sub' [/switches] Input: "string" the main string to be searched 'sub' the substring to search for Output: ErrorLevel - location, [E] length of string. Environment - string. Switches: /Wnum offset to start the search /X starts the operation at the right end of the string. GET # is like the BASIC language INSTR (In String) function. It locates the position of a substring within a string. /X starts the search at the end of the string from right to left. The substring comparison is still left to right, and the position reported is the offset from the beginning of the string. The result is 0 (zero) if the substring is not found in the string, else it is the location starting with 1 for the leftmost character. If no 'sub' is given, the length of string will be reported. If /Woffset is specified, the search will begin at the offset specified; thus, a second or subsequent occurrence can be found. If /x is specified, the offset is counted from right to left. The search is case sensitive. Note: for GET # you cannot include the single quote character (apostrophe) in the substring. Examples: Command Result GET # "D:\subdir\filename.ext" '\' 3 GET # "D:\subdir\filename.ext" '\' /w3 10 GET # "D:\subdir\filename.ext" '\' /x 10 GET # "D:\subdir\filename.ext" '\' /x/w10 10 GET # "D:\subdir\filename.ext" '\' /x/w13 3 GET #E uses the GET # arguments to Extract the string. After skipping /Wn characters, the substring up to but not including 'sub' will be extracted. The ErrorLevel is the length of the extracted substring. If /X is specified, the substring in 'sub' plus everything to the right except the first character will be extracted. On the basis that it is easier in BATch files to catenate strings rather than shorten them, the first character of the target string is likely to be a delimiter of some sort, for example the '\' in a filespec, or the white space between words. The below examples demonstrate how easy it is to extract portions of a filespec. Examples: Command Result ErrorLevel GET #E "D:\subdir\filename.ext" ':' D 1 GET #E "D:\subdir\filename.ext" '\' D: 2 GET #E "D:\subdir\filename.ext" '\' /w3 subdir 6 GET #E "D:\subdir\filename.ext" '\' /x filename.ext 12 GET #E "D:\subdir\filename.ext" '.' /x ext 3 GET #E "D:\subdir\filename.ext" '\' /x/w10 filename.ext 12 GET #E "D:\subdir\filename.ext" '\' /x/w13 subdir\filename.ext 19 Note: There may be a confusing difference between the use of /Wn for GET GET # Locate Substring Page 41 Z[E] and GET #E. For GET Z /Wn specifies the maximum width. For GET # /Wn specifies the offset to start the extraction. In retrospect it would seem to be better to reverse the meaning of 'arg' and /W for GET Z[E], but this would make it incompatible with the previous release. The /T trim switches can be used to trim blanks and Alt-255 characters from either or both ends of the extracted string. Page 42 'Rithmetic GET R GET R 'Rithmetic Syntax: GET R[E] ["+-*/!=&#^~"] [num1] [/Wnum2] [/switches] Input: one or two numbers, maximum of 65535. Output: ErrorLevel - result modulo 256. Environment - arithmetic result Switches: /A ASCII character in Environment /Wnum2 the second number for the arithmetic operation /H Environment result in Hexadecimal R (for 'Rithmetic) performs arithmetic on two numbers. If no arithmetic symbol is given in quotes then: GET R defaults to add the two numbers GET RE subtracts the second from the first The defaults for num1 and num2 are 0 (zero). /H reports the final Environment result in Hexadecimal When numerical input is used for an argument or with /W, the numbers can be as large as 65535. The arithmetic result is in both the Environment and ErrorLevel. If only one number is given, the other number defaults to 0. Thus a character representation of a number can be converted to a number in the ErrorLevel. See examples below for information about results larger than 255 or negative. One of the following arithmetic symbols may be entered as the "prompt" argument. Symbols: "+" the default, adds the two numbers. "-" subtracts num2 from num1 "*" multiplies the two numbers. The maximum product is 655,350. If the multiplication produces a larger product an asterisk will be used to indicate that the result is too large. Note num2 defaults to 0, so if it is not specified, the result will be 0. "/" divides num1 by num2 by integer arithmetic. Only the quotient is returned. See NOTE below. "!" modulo arithmetic. Divides num1 by num2 and returns only the remainder. NOTE: Division by zero is invalid. If num2 is omitted, or is 0, the result will be num1 for "/" or "!". If num1>255 the result will be num1 modulo 256. "=" compares num1 and num2 and returns one of: 0 if num1<num2 1 if num1=num2 2 if num1>num2. This makes it easy to use ErrorLevel to check for >= or <= as well as one of the above. "&" Bitwise logical AND Syntax: GET R "&" num1 /wnum2 GET R 'Rithmetic Page 43 Result: num1 .AND. num2 "#" Bitwise logical OR Syntax: GET R "#" num1 /wnum2 Result: num1 .OR. num2 "^" Bitwise logical XOR Syntax: GET R "^" num1 /wnum2 Result: num1 .XOR. num2 "~" Bitwise logical NOT Syntax: GET R "~" num1 Result: .NOT. num1 $num indicates that num is in Hexadecimal if a number is expected. This is useful for GET R and can be used anyplace a numerical arg or parameter is expected. The # sign works as a prefix to an ASCII character and means use this character as a number. Thus you can perform arithmetic using the numerical value of ASCII characters. The # character, like the $ character for hex, can be used wherever numerical input is expected; however, with the # character only one character immediately following it is converted to the ASCII value of that character. These conversions will be most useful with GET R. /H provides a generalized Hexadecimal capability. Whenever numerical output is expected in the Environment, /H will convert the output to Hexadecimal. The /A (for ASCII) switch in the case of GET R, means put the ErrorLevel in the Environment as an ASCII character. EXAMPLES: 1. Convert a numerical Environment variable to an ErrorLevel. Suppose the following string is in the Environment: VAR=45. Then GET R %VAR% will set the ErrorLevel to 45, and place GET=45 in the Environment. 2. Suppose you need to set up a loop in a BATch file. You can do it this way. SET COUNT=0 :LOOP GET R %COUNT% /W1 /VCOUNT= Echo The count is %COUNT% IF NOT ERRORLEVEL 10 GOTO LOOP 3. You can use GET R to pass a return code from a CALLed BATch file to its parent. Of course, this could have been done by SETting and Environement variable, but with GET R you can use the ErrorLevel if you want. Page 44 'Rithmetic GET R Echo This is the child batch file. Rem Set the default ErrorLevel to 0, suppress Environment variable. GET R 0 /V- Rem Now make tests and set ErrorLevel accordingly. If "%COMSPEC%"=="C:\COMMAND.COM" get r 1 /V- If "%COMSPEC%"=="C:\4DOS.COM" get r 4 /V- @Echo off Rem This is the parent file. CALL CHILD If ErrorLevel 4 Echo 4DOS is loaded. If ErrorLevel 1 Echo COMMAND.COM is loaded. If Not ErrorLevel 1 Echo Unknown command processor. 4. If the result is greater than 255, the ErrorLevel is modulo 256. For example: 256=0, 257=1, ..., 511=255, 512=0, etc. set GET?=on GET R 195 /W350 Environment: 545 ErrorLevel: 33 5. GET uses simple computer integer arithmetic. Negative numbers are not recognized as such. If a larger number is subtracted from smaller, the result is 65536 minus the absolute value of the difference. GET RE 10 /W20 The ErrorLevel is 246 The Environment is 65526 6. Convert a hexadecimal number to decimal GET R $ABC Environment: 2748 ErrorLevel: 188 NOTE: Since the ErrorLevel is limited to a max of 255, the result is reported modulo 256. 7. Add a hexadecimal number to a decimal number GET R 10 /W$A Environment: 20 ErrorLevel: 20 8. Add a hexadecimal number to a decimal number, result in hex GET R 10 /W$A /h Environment: 14 ErrorLevel: 20 9. You want a single digit for the month to use in constructing a filename. Suppose the month is December. GET H 4 /H Environment: C ErrorLevel: 12 GET R 'Rithmetic Page 45 10. Suppose you want a series of characters A, B, C, D, E to construct 5 filenames. With the new methods only one call to GET within the loop is necessary. Rem Establish starting point of first character - 1. GET R "-" #A /W1 /VC= /A Rem Convert the value for the last character. GET R #E /VN= :NAMELOOP Rem Convert last char to num, add 1, and convert back to char. GET R "+" #%C% /W1 /VC= /A Echo Character %C% can be used in a name. IF NOT ERRORLEVEL %N% GOTO NAMELOOP SET C= SET N= 11. Convert a hexadecimal number to an ASCII Character GET R $4F /A Environment: O ErrorLevel: 79 12. Add a hexadecimal number to an ASCII Character, and convert the result to an ASCII character. GET R #A /W$A /A Environment: K ErrorLevel: 75 13. Add a hexadecimal number to an ASCII Character, result in hex GET R #A /W$20 /h Environment: 61 he ErrorLevel is: 97 Page 46 Clear (Blank) Screen GET B GET B Clear (Blank) Screen Syntax: GET B[E] [New attribute] [/switches] Input: desired new attribute in decimal for B, hex for BE. Output: ErrorLevel - old attribute (decimal of course). Environment - old attribute in decimal, hex for BE. Switches: /Anum can be used for new Attribute /Wnum number of rows on the screen /X reports the old number of lines instead of attribute B the screen Blanker actually performs a clear screen, not a true blanking which leaves the screen display intact but merely hides it. By doing so, it is able to control the screen attribute (color). GET B uses your color settings unless you give it a different attribute to use. It automatically adapts to any number of lines on the screen (e.g. EGA 43 or VGA 50). If an attribute argument is given it is taken to be a 1, 2, or 3-digit decimal number that is converted to a two-digit hexadecimal number for the attribute. The same table of colors and attributes that is used for the /A switch is used for the GET B command. GET B can also use the same attributes with /A that the prompt uses. The /W switch can be used with GET B to set the number of roWs on the screen for EGA or VGA monitors. GET B /W25 sets the screen to 25 line mode. GET B /W43 sets EGA screens to 43 line mode, and VGA screens to 50 line mode. If the /X switch is used, GET B will return the current number of lines on the screen instead of the video attribute. This is done by using a BIOS call to load either the default 8x14 or 8x8 font table. Your number of lines may vary depending on your EGA or VGA BIOS. To get 25 line mode, it may work better to use GET V 3 to set video mode 3 instead of GET B /W25. BE regards an argument as a 1 or 2-digit hex number, and the GET value in the Environment is in hex. With GET BE the number will be taken to be in hex whether it has a $ or not, and the Environment value is in hex. GET B can take a $hex number as input but will report in decimal unless /H is used. EXAMPLES: 1. Do a simple ClearScreen (CLS) without changing colors or number of lines. Suppose the old attribute was black and white. Rem Turn on GET reporting feature SET GET?=ON GET B Environment: 7 ErrorLevel: 7 2. Set color to blue background with white text. Save the old attribute in the environment variable ATTR. GET B 23 /VATTR= Environment: 7 ErrorLevel: 7 GET B Clear (Blank) Screen Page 47 3. Restore the saved attribute. GET B %ATTR% Environment: 23 ErrorLevel: 23 Rem Turn off GET reporting feature SET GET?= Page 48 Get/set video mode GET V GET V Get/set video mode Syntax: GET V [New mode] [/switches] Input: optional new video mode. Output: ErrorLevel - old mode Environment - old mode Switches: Global switches only V reports and optionally sets the video mode. Don't change Video mode unless you have a specific reason for doing so to prevent setting a mode that is not supported by the system running the BATch file. The following Video Display Mode table is excerpted from "The New Peter Norton Programmer's Guide to The IBM PC & PS/2," page 72. Mode # Type Resolution Colors Video Subsystem 0, 1 Text 40 x 25 16 CGA, EGA, MCGA, VGA 2, 3 Text 80 x 25 16 CGA, EGA, MCGA, VGA 4, 5 Graphics 320 x 200 4 CGA, EGA, MCGA, VGA 6 Graphics 640 x 200 2 CGA, EGA, MCGA, VGA 7 Text 80 x 25 Mono CGA, EGA, MCGA, VGA 8, 9, 10 PCjr only 11, 12 Used internally 13 Graphics 320 x 200 16 EGA, VGA 14 Graphics 640 x 200 16 EGA, VGA 15 Graphics 640 x 350 Mono EGA, VGA 16 Graphics 640 x 350 16 EGA, VGA 17 Graphics 640 x 480 2 MCGA, VGA 18 Graphics 640 x 480 16 VGA 19 Graphics 320 x 200 25 MCGA, VGA EXAMPLES: 1. Get the current video mode and save it in the variable VIDEO. Change to video mode 2. Later restore the original mode. GET V 2 /vvideo= Rem Do what you need to with mode 2 Rem Restore original mode GET V %VIDEO% Rem Clear out VIDEO variable SET VIDEO= 2. Suppose you have an "ill behaved" program such as a game that leaves the video in a graphics mode when it exits. You can save the orginal mode before executing the game, then restore it later. Rem Store original video mode GET V /vvideo= Rem Run the ill behaved game GAME Rem Restore original mode GET V %VIDEO% GET VE Get/set video border Page 49 GET VE Get/set Video border Syntax: GET VE [New color] [/switches] Input: optional new border color for VE. Output: ErrorLevel - old color Environment - old color Switches: Global switches only VE will get/set the border color on a VGA or EGA monitor. See the color table below. One interesting use is to set different border colors for each of your DESQview windows if you are a DV user. GET VE will take any of the 8 basic color codes 0-7. The additional combinations that can be used for /A or GET B have no meaning for GET VE. The color codes are: 0 Black 2 Green 4 Red 6 Brown 1 Blue 3 Cyan 5 Magenta 7 White EXAMPLES: 1. Set the border color to red. It was black. Rem Turn on GET reporting feature SET GET?=ON GET VE 4 Environment: 0 ErrorLevel: 0 Rem Turn off GET reporting feature SET GET?= Page 50 Date and Time GET H GET H Date and Time Syntax: GET H[E] ["prompt"] code [/switches] Input: Code from the table below Output: ErrorLevel - H: date or time value specified by code HE: country code Environment - date or time value(s) specified by code Switches: /A include leading 0's. /C Compressed date /Sn Overrides country code for date format /Wnum Wait num seconds /X/Wnum Wait until time in 24 hour format H The H Date and Time command works differently than most of the others. The value to be obtained is determined by a coded numerical argument. The codes are as follows with 1 being the default. 1 Day of the Week - Sunday=0 16 Hour 2 Day of the Month 32 Minute 4 Month - January=1 64 Second 8 Year 128 Odd or Even (H only) 512 2-digit year 256 100ths of seconds (H only) For GET H, only one value is returned for each call of GET. The Environment will contain the character representation of the ErrorLevel, except for Year, or for the Odd/Even feature, or if no code is given. Since ErrorLevel has a maximum of 255, only the last two digits of the year will be reported, but the Environment will have the full value. If no code is given, the ErrorLevel will contain the default Day of the Week but no Environment variable will be created. The Odd/Even feature is obtained by adding 128 to the desired code. The Environment will contain the value for the code, but the ErrorLevel will be 1 if the value is odd or 0 if it is even. This provides a means to alternate doing something like running COMPRESS on C: on even days and D: on odd days. A code of 128 by itself will put the odd or even indicator for the Day of the Week in the ErrorLevel but no Environment variable will be created. The code 256 specifies the result to be 100ths of seconds. Code 156 like code 128 works only with GET H, not GET HE. Also remember that code 128 is the only one that can be combined with another code for GET H since GET H returns a single result. HE will place a concatenated string in the environment. You can "build your own" string. HE requires that you add up the codes for the values you want concatenated. With this form of the command the ErrorLevel is the length of the GET variable, but it is not very meaningful or useful. 128 and 256 do nothing for HE either. GET HE displays a 4-digit year if code 8 is included in the argument. This permits years after 1999 to be reported and used. Note: In some earlier versions of DOS and 4DOS the DATE command did not accept a 4- digit year. Current versions work OK. The ErrorLevel for Year is Year- 1900, thus 2000 will be 100, etc. GET HE now will check for a /A switch, and if found will not substitute a GET H Date and Time Page 51 leading blank for a leading 0; i.e., will include leading 0's. If you can find a use for it with HE, you can include a "prompt" string in double quotes. The Environment variable will contain the prompt string with the requested date and/or time information concatenated. /Wnum now means wait for the given number of seconds, then report. /X/Wnum means wait until a minute in 24 hour time, then report. NOTE: The 24 hour time specification must be in military format, no punctuation; e.g., 1135, 0300, 1056, etc. Use 2400 for midnight, not 0000. In either case the wait cannot be longer than 18 hours (65535 seconds). If the 24 hour time is longer than 18 hours hence, it will be reduced to 18 hours. If a number of seconds greater than /W65535 is specified, the results are unpredictable. If the 24 hour time specification is less than the current time, it will be interpreted as meaning going past midnight to the given time on the next day. Internally GET C is used to process the waiting time, thus the wait can be interrupted by pressing any key. If a "prompt" is included, it will be displayed during the wait. Any switches will be used for GET C also, thus /A can be used to control the attribute of the prompt. However, no character 'arg' will be recognized, so any key will interrupt the wait. Although it was possible to accomplish the same thing with GET C /W in previous versions, this feature will make it easier and more precise to specify waiting times in BATch files. If necessary to wait more than 18 hours, more than 1 call to GET can be used to wait various lengths of time, each no more than 18 hours. The date and time functions in GET (H and F) will now report the dates and times in the format specified by the country code that is currently in use. As an adjunct to this change, GET HE now reports the country code in the ErrorLevel. Previously GET HE reported the length of the date/time string which probably was of no use for any application. If the country code is greater than 254, the ErrorLevel will be maxed out at 255. This would affect Portugal, Finland, Israel, and some Arabic language countries. Note that country codes are usually the international telephone prefix. GET H[E] 2-digit year Code 512 has been added as an option for GET H[E]. If 512 is added to the coded numerical argument, the year will be placed in the Environment as the rightmost 2 digits only. Code 512 can either replace 8 or it can be added to 8. Either value will produce the 2-digit year. NOTE: Since the previous version it has been possible to obtain a 2-digit year by adding /R to GET H, but there was no easy way to do it with GET HE. GET HE/FE Date format override. The date format will default to the format for the country specified in DOS. You can override the format with the /Sn switch where n can be 0, 1, or 2 as follows: 0 USA format Month-Day-Year 1 Europe format Day-Month-Year 2 Japan format Year-Month-Day Page 52 Date and Time GET H The date separator will retain the value for the country specified for the operating system, but the order of the values will change according to these format codes. Note that the Japan format with a 2-digit year would be ideal for naming files because they would sort properly in date order. Use GET HE 518 /s2/a. However, countries that use a '/' or '.' character for a separator cannot use it in a filename. Therefore another date format feature has also been added. You can eliminate the separators completely by adding 4 to the date format code with /Sn. Thus n can also be 4, 5, or 6 to suppress the separators and the previous command would be GET HE 518 /S6. As the year 2000 rolls around you might want to use a 4 digit year for proper sorting. Then the command would be GET HE 14 /S6. The /A is not necessary with values of 4, 5, or 6 because leading 0's will automatically be included. For example, you can create an 8 character filename incorporating the date with a command such as GET HE "XX" 518 /S6 where XX can be any two leading characters you want. /S6 puts the two- digit year first to facilitate sorting, and it also eliminates the delimiters as well as including leading 0's. COMPRESSED DATES with the /C switch (think C for Compressed) GET H and GET F /E report dates in compressed form with /C. These dates can be used directly to compare the dates between two files or to compare a file date with today's date. This date format does not have much visual usefulness because it is not directly readable as a date. It can be used to generate unique file names but the names will not be meaningful to view. To report these dates use the /C switch with either GET H /C or GET F filespec /E/C. Other date or file parameters will be ignored but you can use some of the global switches such as /H to report the output in hexadecimal. The date format is independent of the Country setting and the /S switch, as well as any coded date parameter. These are ignored and the date is reported as follows. The /C switch also overrides the Extended functions of GET HE and GET FE/E. The format used is the DOS native internal file date format. It uses 16 bits as follows: BITs fedcba9 8765 43210 Value Year Month Day The year is relative to 1980; e.g., 1995 is 15. Thus to convert to meaningful numbers it is necessary to first convert to binary format then extract the bit fields manually and convert to numbers. The only meaningful date arithmetic that can be done with these numbers is to find the number of days difference but ONLY if both numbers are within the same month. EXAMPLES: See additional examples under GET F /E for Compressed date usage. GET H Date and Time Page 53 1. This is a rather elaborate BATch file that can be called to provide a formatted date. Call it SHOWDATE.BAT. When you call SHOWDATE it will report something like "The date is August 25, 1991". This information could just as easily be stored as an Environment variable for use by other BATch files and programs. @Echo Off GET H 4 If "%GET%"=="12" set MONTH=December If "%GET%"=="11" set MONTH=November If "%GET%"=="10" set MONTH=October If "%GET%"=="9" set MONTH=September If "%GET%"=="8" set MONTH=August If "%GET%"=="7" set MONTH=July If "%GET%"=="6" set MONTH=June If "%GET%"=="5" set MONTH=May If "%GET%"=="4" set MONTH=April If "%GET%"=="3" set MONTH=March If "%GET%"=="2" set MONTH=February If "%GET%"=="1" set MONTH=January Get H 2 /VDAY= Get H 8 /VYR= Echo The date is %MONTH% %DAY%, %YR% 2. A GET BATch file can easily be set up to wait until a given time by using the H feature. In this example the first pair of GET calls checks every 15 minutes for the hour you want to wait until - in this case 11 p.m. or 23 in computer parlance. The next pair of GET calls checks the time once a minute and waits until the minute is 30. The BATch file will continue executing at 11:30 p.m. or shortly thereafter. @echo off :HOUR Check the hour every 15 minutes. GET C /W900 GET H 16 if not "%GET%"=="23" goto HOUR :MINUTE Check the minute every 60 seconds. GET C /W60 GET H 32 if not ErrorLevel 30 goto MINUTE Rem The BATch file will continue here at 11:30 p.m. 3. The above BATch file can be parameterized so it can be called with the hour and minute that you want it to wait until. Name this BATch file WAITFOR.BAT, then at the DOS prompt enter WAITFOR hour minute. For example, WAITFOR 23 30. A BATch file like this can be run in a DESQview window in the background and produce an alarm at a given time, or execute a program in the background or when the computer is unattended. It can easily be tuned down to the minute, or even the second by how fine you make the checkpoint intervals. @echo off :HOUR Check the hour every 15 minutes. GET C /W900 GET H 16 if not "%GET%"=="%1" goto HOUR Page 54 Date and Time GET H :MINUTE Check the minute every 60 seconds. GET C /W60 GET H 32 if not ErrorLevel %2 goto MINUTE Rem The BATch file will continue here at the hour and minute you specify. Rem Sound your alarm, or do whatever here, for example, Echo ^G ^G ^G ^G ^G 4. Here are some BATch statements I use in my AUTOEXEC.BAT to do some things only once a day, such as run DOS 5.0 MIRROR to save a copy of my system information in case of a crash. The current date is saved on disk in a BATch file named SETDATE.BAT. It contains one line, for example: SET DATE=29. When I CALL SETDATE it stores the last saved date in the Environment as the DATE= variable. Then I use GET to get today's date and compare it with %DATE%. If they compare, I know that I have already done my once-a-day procedures and can skip them this time. If they don't compare, a new SETDATE.BAT is automatically created, and the once-a-day statements are executed. Follow it through here: Rem Call SETDATE to store the last saved date in the Environment CALL SETDATE Rem Get today's date to compare with. GET H 2 Rem Compare the last saved date with today's date. IF "%DATE%"=="%GET%" GOTO DATEOK Rem If false, recreate SETDATE with today's date. ECHO SET DATE=%GET% >SETDATE.BAT Rem Do your once-a-day procedures here; for example ... MIRROR D: E: F: Rem If the dates compared we would skip the above lines Rem thus speeding up succeeding boots. DATEOK: Rem Continue with your AUTOEXEC.BAT here. Rem Run MIRROR on your boot drive and load delete tracking for all drives MIRROR C: /TC /TD /TE /TF 5. HE was designed to produce output in the same form required by the DOS DATE and TIME commands. For example, if you need to temporarily change the system date (or time) and later restore it, you can do it with the following BATch file. @Echo off Rem HE 14 will report mm-dd-yy in the Environment: 14=2+4+8. get HE 14 /VDATE= Rem Now set the date as you need it for whatever reason, for example: DATE 6-15-90 Rem Now run the program that requires the new date. Rem . . . Rem Now restore the original date. DATE %DATE% Rem Clear out the DATE variable (unless you want to save it to use again). SET DATE= 6. Display the Day of The Week for any date between 1-1-1980 and 12-31- 2099, then reset the current date. @echo off GET H Date and Time Page 55 set TRY=%1 if not "%1"=="" goto TryDate get s "Enter mm-dd-yyyy: " 99-99-9999 /VTRY= :TryDate GET HE 14 /vDAY= date %TRY% GET H 1 date %DAY% goto DAY%GET% :DAY6 set DOW=Satur goto END :DAY5 set DOW=Fri goto END :DAY4 set DOW=Thurs goto END :DAY3 set DOW=Wednes goto END :DAY2 set DOW=Tues goto END :DAY1 set DOW=Mon goto END :DAY0 set DOW=Sun :END Echo Day of the week for %TRY%: %DOW%day :EXIT Set TRY= Set DAY= Set DOW= Set GET= 7. Catenate a "prompt" string with the date. Rem Turn on the GET reporting feature SET GET?=ON GET HE "The date is" 14 Environment: The date is 8-29-91 ErrorLevel: 20 Rem Turn off the reporting feature SET GET?= 8. Wait until 3 a.m. the next day (or the same day if after midnight) GET HE 112 /x /w300 Environment: 03:00:00 ErrorLevel: 8 9. Wait for 3600 seconds (1 hour). Starting time: 11:30 a.m. GET HE 112 /w3600 Environment: 12:30:00 Page 56 Date and Time GET H ErrorLevel: 8 10. Wait until 11:30 p.m. the same day. GET HE "Waiting until 2330" 112 /x /w2330 Rem the prompt is displayed while waiting. Rem Waiting until 2330 REM After the appropriate wait the results of GET HE 112. Environment: 23:30:00 ErrorLevel: 8 GET U Keyboard BUffer Page 57 GET U Keyboard BUffer Syntax: GET U "chars" num /Wnum [/switches] Input: characters and key codes to place in key buffer Output: ErrorLevel - Number of characters actually stacked Environment - Not used, GET or /V variable will be cleared out. Switches: /Wnum ASCII value for additional character to be stacked U will stack keys in the keyboard bUffer. "chars" are any ASCII characters you want stacked in double quotes, and the "num"s are decimal representations of values for either ASCII codes or scan codes. Up to 3 digits can be used for either number. E.g. to end the string with a carriage return use 13 or /W13. To enter a scan code add it to 255. Note that this is purposely different from the scan code surrogates for the GET C command. NOTE: GET U will only work on PC/XT's with BIOS dated 01/10/86 and later, PC/AT's with BIOS dated 11/15/85 and later, and PS/2s! With GET U you can provide a default entry for a GET S string; however, the DOS keyboard buffer only holds 15 characters, so it has to be rather short. Use GET U "default" followed by GET S "prompt", and the default string will be entered for the user. The user can either change it by backspacing or accept it by pressing enter. The ErrorLevel will contain the number of characters or codes actually placed in the buffer. If the buffer fills up before all the characters or codes are stacked, GET will beep and exit. By testing the ErrorLevel for the number of characters and codes, you can tell if the stacking was successful. To make the full buffer available, the /B switch can be used to clear the buffer. EXAMPLES 1. The following will stack the word "help" in the buffer and execute it as a command by also stacking the Enter key (ASCII 13 for CR). To make the stacked command execute, the BATch file must exit to activate the DOS prompt. GET U "help" 13 /B Rem Test that 5 characters were stacked if ErrorLevel 5 goto EXIT Rem Not all characters were stacked, so clear the buffer and exit GET I /B :EXIT 2. The scan code for F1 is decimal 59 so use 314 (=59+255). The following command will stack the F1 key (The HELP key for 4DOS): GET U 314 Page 58 Keyboard BUffer GET U 3. Some programs pause when they are loading and require the user to press a key to continue. If the program does not clear the keyboard buffer, then GET U can stack the keystroke(s) to automate the loading of the program. It could also automate the first few program command keys. In this example we will stack the characters to bring up a spreadsheet file list in Quattro Pro. Rem /FR is the Retrieve command for Quattro Pro GET U "/FR" Rem Now call Quattro Pro - the spreadsheet list will be displayed. Q GET UE Shift Locks Page 59 GET UE Shift Locks Syntax: GET UE [/Wnum] [/switches] Input: numerical code to set or clear keyboard locks. Output: ErrorLevel - Old value Environment - Old value Switches: /Wnum code for locks to set UE will let you adjust the Caps, Num, and Scroll Locks. Sum the numbers for Scroll=16, Num=32, Caps=64 for the Locks you want to set. The other(s) will be cleared. You must use GET UE /Wnum not just GET UE num. CAUTION: Don't forget the /W. EXAMPLES 1. Turn off NumLock and ScrollLock, turn on CapsLock GET UE /W64 2. Turn on both NumLock and CapsLock, turn off ScrollLock. Rem Turn on GET reporting feature SET GET?=ON GET UE /W96 Environment: 64 ErrorLevel: 64 3. Turn off all key locks GET UE Environment: 96 ErrorLevel: 96 Rem Turn off GET reporting feature SET GET?= 4. Turn on CapsLock, then restore original setting Rem Turn on Caps and Num Locks to get user input Rem Save original setting in LOCK. GET UE /W96 /VLOCK= Rem Get string input from user in upper case and numbers. GET S "Enter information now: " Rem Restore original lock settings GET UE /W%LOCK% Rem Clear out the LOCK variable SET LOCK= Page 60 Get DISK and FILE Information GET 2.7 GET DISK and FILE Information The K, Q, L, F, FP, X, and Y commands obtain information about disks and/or files. Note that Q, K, and L check to see if the drive contains a formatted disk, and they return an ErrorLevel 0 if it does not. This avoids the Abort, Retry, etc. error handling. If the ErrorLevel is 0 the error code will be in %GET% as a hexadecimal value. Some error code values of interest when running under DOS are: 1 Invalid drive specified - this new procedure works only for drives on the primary disk controller, usually A: and B:. 2 Address mark not found meaning disk is not formatted 6 Floppy disk has been removed. If this code is returned, try again since it may persist even if the drive door has been opened and closed again, especially if a disk cache is in use. 20 Controller failed meaning disk is not formatted. 80 Drive timed out probably because door is open Other codes that may be seen - test on your system: 3 disk write protected may mean no diskette in drive. 4 sector not found - possible if disk is not formatted. 8 and 9 DMA errors (unlikely) C media type not found - possible if disk is not formatted. 10 data error - formatted disk in drive but is unreadable 40 seek failed (unlikely) . When GET is running in an OS/2 DOS session the old method of checking is still used due to an incompatibility and the old error codes will be reported: 0 - Write protected diskette (n/a since GET does not write) 1 - Invalid drive letter 2 - Drive not ready - no disk or door open. 4, 6, 7, 8, & B - Disk read errors C - General, nonspecific error. F - Invalid disk change GET K, Q, and L /A switch Two methods of testing are available--a standard DOS method, and one that is used in an OS/2 VDM. The DOS method is faster in DOS but slower and less reliable under OS/2. If the default DOS method does not give the desired results for something you want to do, you can try the /A (for Alternate method) switch to force GET to use the same method that is used under OS/2. This is the method used by some older versions of GET such as 2.5, and it can be very slow if there is an unformatted diskette in the drive. Remember. the two methods return different error codes as described in the manual. When used on drives other than A: and B: in previous versions of GET, this test often failed due to technical reasons even if valid media was in place, and it interfered with obtaining the size or label of some drives such as removable and network drives. GET 2.7 Get DISK and FILE Information Page 61 GET K, Q, and L /X switch A /X switch has been added to check for a writeable disk in drive A: or B:. First GET checks for a formatted disk in the usual manner of GET Q, K, and L. If this test fails, the ErrorLevel will be 0 and the return code in the Environment. If this test passes, then an attempt is made to write to the disk, but no data will actually be written. If the disk is write protected an ErrorLevel of 0 and an Environment variable (error code) of 3 will be reported. If the status cannot be determined, an ErrorLevel and Environment variable of 0 are reported. If these tests are passed, then the normal return from GET K, Q, or L will be reported. The read and write tests will always be bypassed if the drive is other than A: or B:. This may be inconvenient for those rare users who have a 3rd floppy drive other than A: or B:, but it should be usable in 99.44% of the cases. It also does not test other types of drives with removable media such as Bernoulli drives. The benefit of this restriction is that it permits obtaining size and label information on more types of drives including possibly some network drives. This benefit is thought to more than compensate for the occasional Abort, Retry, Ignore type message on the odd removable drive other than A: or B:. INTERNATIONAL DATES AND TIMES SUPPORTED The date and time functions in GET (H and F) will now report the dates and times in the format specified by the country code that is currently in use. (See additional information under GET H below.) Page 62 Get disk free space GET K GET K Get disk free space Syntax: GET K[E] [drive][/Wdiv] [/switches] Input: drive letter and optionally divisor Output: ErrorLevel - KiloBytes/10, KE - KiloBytes/100 Environment - KiloBytes Switches: /A Alternate method to test floppy drive /Wnum divisor for ErrorLevel /X Check for write protected diskette K takes the argument to be a drive letter. The colon is not required. The default is the current drive. Optionally a divisor can be included with the /W switch. K, as well as Q and L, starts out by attempting a direct read of the disk. If this fails by reason of one of the errors mentioned above, GET reports the error and exits. This avoids the annoying "Abort, Retry, Ignore, Fail?" message if the drive is not ready for some reason, and lets the BATch programmer handle the error as appropriate to the application. If the read is successful, GET K obtains the disk information and calculates the free space. Please see the information at the beginning of this section on "GET DISK and FILE Information" for general information regarding the /A and /X switches. Disk free space is reported in kilobytes (kb) in the Environment. To verify the value you can take the free space reported by CHKDSK and divide it by 1024, the number of bytes in a kb. The result should come out exactly. The value reported in the Environment is the same for GET K and GET KE. Since the ErrorLevel can only report numbers up to 255, GET reduces the value that is reported, but this does not affect the value in the Environment. For GET K the number of kb is divided by 10, and for GET KE, the kb is divided by 100. For disks with very large partitions, this may still not reduce the amount reported below 255, so GET also has provisions for an optional programmer supplied divisor. For example, an argument of /W1024 will divide by 1024, and the ErrorLevel will contain approximate megabytes of free space. EXAMPLES: 1. Assume that CHKDSK reports "8,386,560 bytes available on disk". Then GET K reports Rem Turn on GET reporting feature SET GET?=ON GET K Environment: 8190 ErrorLevel: 255 In this case 8190 divided by 10 is 819, a figure too large for the ErrorLevel, so the ErrorLevel is set to the maximum value. 2. Same assumption as 1. GET KE reports GET K Get disk free space Page 63 GET KE Environment: 8190 ErrorLevel: 81 In this case the kb is divided by 100 and truncated by integer arithmetic to 81. 3. Same assumption as 1. Suppose we want the free space in megabytes (mb) on drive C:. GET K C /W1024 Environment: 8190 ErrorLevel: 7 In this case, 8190 divided by 1024 is just under 8, but is truncated to 7 by the integer arithmetic used. The BATch file is assured of at least 7 mb free. 4. Obtain the free space on the diskette in drive B. Assume that CHKDSK reports 700,416 free. GET K b Environment: 684 ErrorLevel: 68 Rem Turn off GET reporting feature SET GET?= 5. No diskette in drive A:. The error may be reported as 2 or C. GET K A if not errorlevel 1 if not "%GET%"=="" goto DiskError Echo The free space on drive A: is %GET% goto exit :DiskError Echo Disk error %GET% on drive A:. :exit Page 64 Get Disk Capacity (Quota) GET Q GET Q Get Disk Capacity (Quota) Syntax: GET Q[E] [drive][/Wdiv] [/switches] Input: drive letter and optionally divisor Output: ErrorLevel - KiloBytes/10, QE - KiloBytes/100 Environment - KiloBytes Switches: /A Alternate method to test floppy drive /Wnum divisor for ErrorLevel /X Check for write protected diskette Q reports the capacity of a disk. GET Q works just like GET K except that it returns the capacity of the disk as if it were empty. Q for Quota? As with K, Q first determines that a formatted disk is present in the drive. Please see the information at the beginning of this section on "GET DISK and FILE Information" for general information regarding the /A and /X switches. Q will most often be used to determine the type of diskette in a floppy disk drive although it will work on a hard disk as well, if that is of interest. Before Q can make this determination, the disk must be formatted, so it cannot be used to select the type of formatting to use in a BATch file. For both Q and K the extended command divides the ErrorLevel by 100 but does not change the Environment variable. If you need a different divisor for the ErrorLevel for K or Q, you can use the /W notation. This divisor feature will be needed to get ErrorLevel information on large partitions. EXAMPLES: 1. A 360k diskette is in drive A:. CHKDSK reports "362,496 bytes total disk space". Rem Turn on GET reporting feature SET GET?=ON GET Q A Environment: 354 ErrorLevel: 35 That's right, in computer terms there are only 354kb on a nominal 360k diskette after space is set aside for the boot record, FAT, and root directory. By the way, I think you will find that GET reports faster than CHKDSK in spite of taking time to try the direct read to check for drive ready. 2. A 1.2mb diskette is in drive A:. CHKDSK reports 1,213,952 total. GET QE A Environment: 1185 ErrorLevel: 11 3. A 720k diskette is in drive B:. CHKDSK reports 730,416 bytes. GET Q b Environment: 713 GET Q Get Disk Capacity (Quota) Page 65 ErrorLevel: 71 4. A 1.44mb disk is in drive B:. CHKDSK reports 1,457,664 total bytes. GET Q B Environment: 1423 ErrorLevel: 142 5. CHKDSK reports 33,449,984 bytes total disk space on drive C:. Use GET to find the number of megabytes in the ErrorLevel. GET Q c /w1024 Environment: 32666 ErrorLevel: 31 Rem Turn off GET reporting feature SET GET?= 6. There is no drive Z:. The error may be reported as 1 or C. GET Q Z if not ErrorLevel 1 if not "%GET%"=="" goto DiskError Echo The disk in drive Z: has %GET% kilobyte capacity goto exit :DiskError if %GET%==1 Echo Invalid drive letter: Z. if %GET%==C Echo General failure on drive Z. :exit Page 66 Get volume label GET L GET L Get volume label Syntax: GET L [drive] Input: optional drive letter Output: ErrorLevel - 1=label found, 0=no label found Environment - Volume Label Switches: /A Alternate method to test floppy drive /X Check for write protected diskette L gets the Volume Label of the specified disk. The ErrorLevel is 0 if the disk is not labelled, or 1 if the disk has a volume label. The optional argument is the drive letter, defaulting to the current drive. If the disk is not labelled, the GET variable will be expunged and the ErrorLevel will be 0. Please see the information at the beginning of this section on "GET DISK and FILE Information" for general information regarding the /A and /X switches. Volume labels can be placed on disks when they are formatted by using the /V switch with the FORMAT command, or later by using the DOS LABEL command, or other labelling utility. Volume labels can be very useful in identifying and cataloging diskettes, especially when they can be checked automatically with a program such as GET. Another use is to verify that the user has inserted the correct diskette when running an installation BATch program. Volume labels can be up to 11 characters. DOS will allow any of the 256 ASCII and extended characters except ."/\[]:*|<>;,?, ASCII 0-31, and the lower case alphabetic characters. (Actually some LABEL programs allow lower case and other characters such as the decimal point, but since DOS converts lower case to caps and will not allow some characters it is better to stick with caps and standard DOS labels.) Even the space character is allowable in a Volume label. Therefore, with 184 characters to choose from, there is an almost endless set of combinations that you can use. To enter the extended characters above 127 hold down the Alt key while typing the ASCII code on the number pad keys. (On some systems it is necessary to hold down both the Alt and the Shift keys while typing an extended character. You may be able to enter ASCII 127 with the Ctrl-BackSpace key.) The file SCANCODE.DOC with the registered version contains a table of all the ASCII characters. It is often convenient to have a space in a volume label, but most versions of DOS make it difficult to verify such a label with the BATch IF subcommand. To DOS the space is a delimiter, and the IF comparison will fail, usually with some message such as "Bad command or file name". To work around this problem, GET provides a method to compare a string, which may include one or more spaces, with the volume label of a disk by using the LE command. The test label is given in the argument and must be enclosed in double quote characters. The comparison is exact and case sensitive, so get it right the first time. If the string is less than 11 characters long, do not include any trailing spaces to fill in the 11 characters. Only the characters up to the last non-space character will be checked and additional spaces will cause the comparison to fail. If you need to test with the IF subcommand, the /U GET L Get volume label Page 67 switch will force lowercase letters (if any) to uppercase, and will convert spaces to ASCII 255 characters. EXAMPLES: 1. The disk in drive B: does not have a volume label. Rem Turn on GET reporting feature SET GET?=ON GET L B ErrorLevel: 0 2. The disk in drive A: has the volume label BOB STEPHAN. GET L A Environment: BOB STEPHAN ErrorLevel: 1 3. The disk in drive A: is not formatted. The error may be reported as 'C' or one of the read error codes above. Even though there is a value in the environment, the ErrorLevel of 0 is sufficient to determine that the disk does not have a volume label. GET L A if not errorlevel 1 goto NoLabel Echo The label on the disk in drive A: is %GET% goto exit :NoLabel if not "%GET%"=="" goto DiskError Echo There is no volume label on the disk in drive A: goto exit :DiskError Echo Error %GET% reading disk in drive A: :exit Page 68 Match volume label GET LE GET LE Match volume label Syntax: GET LE "label" [drive] Input: "label" for LE to match, optional drive letter Output: ErrorLevel - 1 =yes, 0=no Environment - Volume Label Switches: /A Alternate method to test floppy drive /X Check for write protected diskette LE takes a trial label in the "label" argument and sets the ErrorLevel to indicate whether the disk label matches. The comparison is case sensitive and there must not be any trailing blanks in the "label" argument. The /U and /L switches affect only what is placed into the Enviroment string and do not affect the comparison. EXAMPLES: 1. Compare the volume label on the disk in drive A: with the string "BOB STEPHAN" GET LE "BOB STEPHAN" A Environment: BOB STEPHAN ErrorLevel: 1 2. Compare the volume label on the disk in drive A: with the string "BOB" GET LE "BOB" A Environment: BOB STEPHAN ErrorLevel: 0 Rem Turn off GET reporting feature SET GET?= GET F Get file size Page 69 GET F Get file size (DIR=0) Syntax: GET F[E] filespec [/switches] Input: file specification, optionally including path, but no wildcards. Output: ErrorLevel - F: KiloBytes; FE: KiloBytes/10. With /A: Bytes (up to 255). Environment - file size in KiloBytes, Bytes, or Hex bytes Switches: /A All bytes (full file size) /E reports file date/time (See GET F /E next) /Wnum divisor for ErrorLevel /X Exact file size in Environment in hexadecimal The file specification (filespec) is NOT in quotes and must not contain wild card characters, but may contain drive and path information. F reports file size. The result is reported as kilobytes which allows sizes up to 261,120 bytes to be reported in the ErrorLevel. For FE the divisor is 10 so that files up to 2,611,200 bytes can be reported in the ErrorLevel. The /Wnum switch can be used to specify a divisor for either F or FE in the same manner as for GET K and GET Q. The size in kilobytes will be divided by the divisor and the result placed in the ErrorLevel. These divisions affect the ErrorLevel only, the value in the Environment will not be changed. Values in the Environment can be up to 655,530 kilobytes. If it is possible to have larger files on your system, the value for a larger file will be reported as an asterisk indicating that the value is not valid, but is larger than 655,530 kilobytes (671,262,720 bytes). If /A is specified, All the bytes in the file size will be reported in the Environment for files up to 655,350 bytes. If over that size, the value will be an asterisk indicating that the size is larger than 655,350 bytes. If the file is 255 bytes or less, the full size will be in the ErrorLevel. The /Wdiv switch can be used to specify a divisor for larger files so that the resulting ErrorLevel will be less than 255. The divisor does not affect the Environment variable. The /X switch will cause the exact file size to be reported in the Environment in hexadecimal. If the filespec cannot be found, the GET variable will be expunged from the Environment and a standard DOS error code will be returned in the ErrorLevel. (See codes below). Directory existence: The F command for GET Filesize can be used to determine whether a named directory exists. If the filespec is a directory, the ErrorLevel will be 0 and the Environment variable will be '0'. GET F will accept a root directory specification and treat it the same as a subdirectory by reporting an ErrorLevel of 0 and setting the Environment variable to 0 also. However, since the root directory is not a file, the result may be dependent on the version of DOS. It has only been tested with MS-DOS 5.0 and may work differently on older versions of DOS. If your application may sometimes use GET F for a root directory, test it with all versions of DOS that it may encounter to determine the results that will be reported. If an invalid drive is Page 70 Get file size GET F specified in the filespec, the ErrorLevel will probably be 3 (path not found) and the Environment variable will be empty. Remember that GET F does not check for a valid disk in the drive, so if you are checking A: or B: and there is a chance that there may not be a formatted diskette in the drive, use GET K, Q, or L first to verify it. Checking for a formatted diskette each time would slow GET F down with the extra overhead which is unnecessary in most cases. NOTE: Although it is a documented procedure in MS DOS 5.0, do not use the NUL device to check for a directory if any users might be using DR DOS 5.0 or a network. DR DOS 5 thinks that the NUL (and other) devices exist even in non-existent directories. It may be that a few other versions of DOS do not support the NUL device method of checking, but GET will work with them all. GET F must open the file for reading in order to obtain the requested information. This means that GET F may fail on files that cannot be opened in this manner. Although special handling is implemented for directories (which GET cannot open as files), there are other cases where GET may return the code 5 meaning "Access denied". Such cases include, but may not be limited to files on network drives for which read access has not been granted, files opened by other processes, volume label names, and possibly root directories in older versions of DOS. The following return codes are of particular interest for GET F. 2 for "File not found" 3 for "Path not found" (this may also be returned for an invalid drive specification). 5 for "Access denied" 15 for "Invalid drive" For example: GET F "d:\mydir\xxx" will return 2 if the path is found but not the file named XXX, a 3 if the path D:\MYDIR is not found, or a 15 if there is no D: drive. GET F "d:\mydir" will return either 2 or 15 since it is not clear whether MYDIR is supposed to be a file or a path. Whenever the item specified in the filespec may not exist, always check for an empty GET variable (IF "%GET%"=="") which indicates that an error code is in the ErrorLevel. Device Drivers: GET F can be used as a means of communication between your CONFIG.SYS and your AUTOEXEC.BAT. GET F will take the name of a device driver that may have been loaded in CONFIG.SYS and check to see if it has, in fact been loaded. The response will be similar to that for a DIR; i.e. if the driver is loaded, 0 in the ErrorLevel and "0" in the Environment. If the driver is not loaded, the Environment variable will be empty, and the ErrorLevel will contain an error code, usually 2. CAUTION! The name you use for the driver must be the INTERNAL name, not necessarily the same name you use in CONFIG.SYS. Most memory mapping commands and programs will show the internal name that you must use. This method will not work for ANSI.SYS and its clones because they use the name CON, but GET A is available to determine whether ANSI.SYS is loaded. (With all that said, it is only fair to point out that you can accomplish the same effect with IF EXIST by using the internal name of the device driver. Also, remember that TSR's loaded in AUTOEXEC.BAT are not device drivers and cannot be checked this way.) NOTES: (1) In version 2.5 and earlier GET F /E worked the same as GET F GET F Get file size Page 71 /X. This has been changed and any BATch programs that used GET F /E must be changed to use GET F /X instead to get the exact file size. See additional date format information under GET F /E below (2) GET F does not open a subdirectory as a file and therefore cannot obtain the date of a subdirectory. For GET F ... /E, if the filespec is a subdirectory, the ErrorLevel will be 0 and the Environment variable will be empty. Root directories will probably return the same result, but see information on root directories above. (3) For GET F, /X will still report the full filesize in hex even if the errorlevel is in kilobytes (/A not being used), while /H will report kilobytes in hex unless /A is being used. Sorry if this is a bit confusing. (4) GET F will also accept the \ as the last character of the filespec if it is a directory. A trailing \ will be ignored, so it doesn't necessarily specify a directory. For a root directory, the \ is required. EXAMPLES: 1. Check to see if the device QEMM is loaded. The internal name for QEMM is QEMM386$. In this example, the driver is loaded. Rem Turn on GET reporting feature SET GET?=ON get F QEMM386$ Environment: 0 ErrorLevel: 0 2. Same example, but QEMM is not loaded. get F QEMM386$ ErrorLevel: 2 3. Check for the existence of a directory named D:\QPRO\WQ1. IN this example the directory exists. GET F D:\QPRO\WQ1 Environment: 0 ErrorLevel: 0 4. Same example, but the directory does not exist. The ErrorLevel is reported as 2 meaning "File not found" because it cannot be determined of WQ1 is a file or a subdirectory. GET F D:\QPRO\WQ1 ErrorLevel: 2 5. Suppose a file named d:\qpro\wq1\taxes.wq1 is a valid file name. Using GET F to get the file size could produce any of the following results. Rem If you enter an invalid directory: GET F D:\QPRO\WQ\TAXES.WQ1 ErrorLevel: 3 Page 72 Get file size GET F Rem If the file does not exist after all: GET F D:\QPRO\WQ1\TAXES.WQ1 ErrorLevel: 2 Rem If the file is found to have 23,129 bytes: GET F D:\QPRO\WQ1\TAXES.WQ1 Environment: 23 ErrorLevel: 23 GET F D:\QPRO\WQ1\TAXES.WQ1 /X Environment: 5A59 ErrorLevel: 23 Rem Turn off GET reporting feature SET GET?= 6. Suppose you have a file of exactly 166,816 bytes. You could see the following results. GET F filespec Environment: 163 ErrorLevel: 163 GET F filespec /A Environment: 166816 ErrorLevel: 255 GET F filespec /A /W1000 Environment: 166816 ErrorLevel: 166 GET F filespec /A /W1000 /X Environment: 28BA0 ErrorLevel: 166 7. Suppose we have a file we want to copy to drive B:, but we want to check if there is enough space for it. Note that file size is rounded up and disk space is truncated by integer arithmetic so the result here will err on the safe side if at all. Since GET F reports kilobytes in the ErrorLevel, and GET K reports kilobytes in the Environment, we can test as follows: @echo off Rem First get the disk free space on drive B: and save it in FREE= get k b /VFREE= Rem Check for error if not errorlevel 1 goto error Rem Now get the size of the file and check if there is enough room. get f filename.ext Rem Check for error if "%GET%"=="" goto error Rem If the ErrorLevel is not greater than the free kilobytes goto sizeok. if not errorlevel %FREE% goto sizeok Echo There is insufficient space on Drive B: for filename.ext. goto exit :sizeok copy filename.exe b: goto exit GET F Get file size Page 73 :error Echo An error has occurred :exit Rem Clear out the FREE variable SET FREE= 8. Use GET to estimate the number of minutes it will take to transfer a file at different transmission speeds. Since the /Wdiv switch for GET F only affects the ErrorLevel, we can use /R to put the resulting value in the Environment also. Some preliminary math is used in the 9600 and 14400 calculations to reduce the divisor. To keep it simpler, no adjustments are made if the file is larger than 655360. @echo off if "%1"=="" goto HELP Rem Get file size in bytes, store in SIZE= GET F %1 /VSIZE= /A if "%SIZE"=="" GOTO NOTFOUND if "%SIZE%"=="*" GOTO TOOBIG echo Minimum transfer time for a file size of %SIZE% GET F %1 /r /w7200 /a echo at 1200 bps = %GET% minutes GET F %1 /r /w14400 /a echo at 2400 bps = %GET% minutes Rem Get file size in Kilobytes (*1024) Rem SIZE/1060*60 ≈ SIZE/1024*62 GET F %1 /W62 /R echo at 9600 bps = %GET% minutes Rem SIZE/1650*60 ≈ SIZE/1024*97 GET F %1 /W97 /R echo at 14400 bps = %GET% minutes GOTO END :NOTFOUND Echo File %1 not found. GOTO HELP :TOOBIG Echo File %1 is too large. Max size is 655360. :HELP Echo The argument (%%1) is a file specification Echo bps = bits per second, cps = characters per second Echo for 12-2400, we use 10 bits / character (8 + start + stop) Echo for v.32, we est 8-9 bits / character Echo therefore Echo 1200 bps = max of 120 cps Echo 2400 bps = max of 240 cps Echo 9600 bps = est of 1000-1100 cps, use est 1060 Echo 14400 bps = est of 1600-1700 cps, use est 1650 :END SET SIZE= SET GET= Page 74 Get file date GET F /E GET F /E Get file date Syntax: GET F[E] filespec [/switches] /E Input: file specification, optionally including path, but no wildcards. Output: ErrorLevel - F: file date or time value specified by /Wn FE: current country code Environment - date or time value(s) specified by /Wn Switches: /A include leading 0's. /C Compressed dates (see below) /E required /Sn Overrides country code for date format (See GET H) GET F with the /E switch returns the File DATE and/or TIME information in the same manner as GET H[E]. See the description of GET H for additional date and time format information. The /E switch specifies that GET F return the date/time instead of the file size. The number n in /Wn uses the same coding as GET H[E] to return the date/time information; i.e. 2=Day of the Month, 4=Month, 8=Year, 512=2-digit year, 16=Hour, 32=Minute, and 64=Second. These are the only valid codes. The default is 2 for Day of the month (DOM). In other respects, GET F[E] /E works the same as GET H[E] for reporting the date information, and the format will be the same as for system date/time information as reported by GET H. International date/timeformats have been implemented and the /S and /C switches work as specified for GET H[E]. NOTES: (1) In version 2.5 and earlier GET F /E worked the same as GET F /X. This has been changed and any BATch programs that used GET F /E must be changed to use GET F /X instead to get the exact file size. (2) See additional date format information under GET H, including International date formats, the use of the /S switch to override the date format, and the /C switch to give the date in a Compressed format. COMPRESSED DATES with the /C switch (think C for Compressed) GET H and GET F /E report dates in compressed form with /C. These dates can be used directly to compare the dates between two files or to compare a file date with today's date. This date format does not have much visual usefulness because it is not directly readable as a date. It can be used to generate unique file names but the names will not be meaningful to view. To report these dates use the /C switch with either GET H /C or GET F filespec /E/C. Other date or file parameters will be ignored but you can use some of the global switches such as /H to report the output in hexadecimal. The date format is independent of the Country setting and the /S switch, as well as any coded date parameter. These are ignored and the date is reported as follows. The /C switch also overrides the Extended functions of GET HE and GET FE/E. The format used is the DOS native internal file date format. It uses 16 bits as follows: GET F Get file date Page 75 BITs fedcba9 8765 43210 Value Year Month Day The year is relative to 1980; e.g., 1995 is 15. Thus to convert to meaningful numbers it is necessary to first convert to binary format then extract the bit fields manually and convert to numbers. The only meaningful date arithmetic that can be done with these numbers is to find the number of days difference but ONLY if both numbers are within the same month. Examples: 1. Compare two file dates. GET F file1 /C/E/VF1= GET F file2 /C/E/VF2= GET R "=" %F1% /W%F2% Note that GET R returns the values 0 if F1<F2 1 if F1=F2 2 if F1>F2 2. Compare a file date with today's date. GET H /C /VTODAY= GET F file /C/E/VFDATE= GET R "=" %FDATE% /W%TODAY% Remember that the GET HE 14 function can be used to save today's date, then you can set the system date with the DOS DATE command, and finally you can reset it from the saved date. That provides the capability to compare a file date with any selected date. 3. Find how many days older than today the file is. The first check is to see if they are in the same month, assuming that the same month is in the current year. GET H 4 /VTODAY= GET F %1 /E/W4/VFDATE= if "%TODAY%"=="%FDATE%" goto COMPARE ECHO The months do not compare goto QUIT :COMPARE GET H /C /VTODAY= GET F %1 /C/E/VFDATE= GET R "-" %TODAY% /W%FDATE% Echo The file is %GET% days old :QUIT Page 76 Get Full Path GET FP GET FP Get Full Path Syntax: GET FP filespec Input: A file name optionally qualified with a full or partial path. Output: The full path leading to that file. GET FP returns the same information as MS-DOS 5.0's TRUENAME command. (GET FP requires DOS 3.0 or later). Switches: Global only For a given filespec GET FP returns the full path leading to that file. Letters are converted to uppercase, and forward slashes are converted to backslashes; however, if you use forward slashes you must enclose the filespec in single quotes (e.g. 'filespec'). The ErrorLevel is the subdirectory level similar to GET Y. Note that the filespec does not have to exist and this is not a test for existence of a given file. The full path that is returned will be the one to the filespec as if it did exist. If a test for existence is required, GET F can be applied to the result of GET FP, or you can use the DOS IF EXIST subcommand. If the filespec given is the name of a directory, it must end in a backslash (\). Examples: GET FP C:\DOS\ or GET FP \DOS\. If no filespec is given, the current directory on the logged drive will be returned. If just a drive specification is given, the colon (:) is required and the current directory on that drive will be returned. If the given path string is on a JOINed drive, the returned name is the one that would be needed if the driver were not JOINed. Similarly for a SUBSTed, ASSIGNed, or network drive letter. The full path on a local drive always starts with the drive letter (d:), those on network drives always start with \\. EXAMPLES: 1. Use GET FP to get the full path for a file named TEST.EXE. subst d: c:\util\test GET FP d:\test.exe And the result is C:\UTIL\TEST\TEST.EXE 2. Find the current directory on a drive other than the logged drive. (The colon is required). GET FP e: And the result is (if the current directory on E: is \CURRENT). E:\CURRENT 3. Find the parent directory of the current directory on drive E: GET FP E:.. And the result is (if the current directory on E: is \CURRENT). E:\ Note that the parent directory of the root directory does not exist so such a result would be no Environment variable and an ErrorLevel of 0. GET FP Get Full Path Page 77 GET FP requires MS-DOS or PC-DOS 3.0 or above, DR DOS or Novell DOS 6.0 or above, or OS/2 version 2.0 or above. It may not be able to determine the true name if you use "nested" JOIN or SUBST commands, or on a network which does not report true names properly. Page 78 Execute Program GET X GET X Execute Program Syntax: GET X "d:\path\program.ext" ' progargs' [/switches] Input: Program name and arguments Output: ErrorLevel - Return code from program Environment - Return code from program Switches: Global only GET X provides a method of getting the return code (ErrorLevel) from a program into the Environment, and XE provides a way to learn the execution path of GET itself. "program" is the name of the program you want to run. It must be fully qualified with drive, path, and extension of either .COM or .EXE (no BATch files). The exceptions are if the program is on the current drive, or in the current directory, in which cases drive and\or directory will default to current. Do not include any spaces inside the double quotes. You can use .. for the parent directory of the current subdirectory, and . for the current directory, however the latter is not needed since it will default to the current directory. ' progargs' are the arguments, parameters, and switches for the program you want to run. Notice the space following the first quote! Many programs require that the first character in the "command tail" be a space, so it is good practice to start the argument string with a space. It is also good practice to enclose the progargs in single quotes; however, if no spaces are included, the quotes are not absolutely necessary. [/switches] are the optional switches for GET, such as /M for the master environment, or /V to designate the variable name. Any switches for the program must be included in progargs. If GET X is successfull in loading and running the designated program, the ErrorLevel from the program will be in both the Environment and the ErrorLevel when GET terminates. If GET X is not successful, the Environment variable will be empty, and the ErrorLevel will contain a reason for the failure such as: 2 File not found - check the file specifications. 3 Path not found - check the drive and path information 4 Too many open files - increase the FILES= in CONFIG.SYS. 5 Access denied - check for proper .COM or .EXE extension 8 Not enough memory If GET X is successful but the "child" program terminates abnormally, there will be no Environment variable, and the ErrorLevel will be one of the following: 21 Child program was terminated by Ctrl-C or Ctrl-Break. 22 Critical device error - e.g. answering "a" to "Abort, Retry, Fail". 23 Child program stayed resident as a TSR. This should never happen because you should not load a TSR in this manner. GET XE GET's Path Page 79 GET XE GET's Path Syntax: GET XE [/switches] Input: none Output: ErrorLevel - ASCII code of the drive Environment - The path from which GET.EXE was executed Switches: Global only GET XE places the eXecution path of GET.EXE in the Environment,including the drive, path, name, and extension of the file and location from which GET is executing. The ErrorLevel will be the ASCII code of the drive; e.g. 65 for A, 66 for B, etc. This can be useful on an installation disk to determine the drive from which the installation program is running. Requires DOS 3+. Page 80 Drive and Directory GET Y GET Y Drive and Directory Syntax: GET Y[E] [drive for Y] [/switches] Input: optional drive letter for Y, none for YE Output: ErrorLevel - Y: directory level, root=0; YE: current drive, A=0. Environment - directory path (Y) or drive letter (YE). Switches: /X for Boot Drive Y gets the current directory for the default or a specified drive. It takes an optional drive letter argument (the : is not necessary) which defaults to the current drive if omitted. The ErrorLevel reports the directory level - 0 = root directory, 1 for first subdirectory level, etc. Note that DOS maintains a "current directory" for each drive, not just for the logged drive, so it makes sense to inquire about the current directory on a drive other than the logged drive. YE returns the current (or logged) drive. The drive letter is in the Environment, and the drive number in the ErrorLevel - 0=A, 1=B, etc. BOOT DRIVE: The /X switch with GET YE reports the Boot drive using the same codes and format as GET YE. This feature may require DOS 4.0 or later. EXAMPLES: 1. Suppose the following conditions exist - logged drive is C:, current directory on C: is C:\DOS, current directory on D: is D:\QPRO\WQ1, there is no E: drive, a floppy disk with no subdirectories is in B:. GET commands will report as follows: Rem Turn on GET reporting feature SET GET?=ON GET Y Environment: \DOS ErrorLevel: 1 GET Y D Environment: \QPRO\WQ1 ErrorLevel: 2 Rem Get the current drive and directory, and combine them to make Rem a full path that does not end in a trailing backslash. GET YE /VDIR= Environment: C ErrorLevel: 2 GET Y Environment: \DOS ErrorLevel: 1 if not ErrorLevel 1 set GET= SET DIR=%DIR%:%GET% GET Y B Environment: \ ErrorLevel: 0 Note: The root directory is the only case that GET ends the Environment variable with the \ character. (It is easier to add one than to drop GET Y Drive and Directory Page 81 it off.) GET Y E ErrorLevel: 0 Turn off GET reporting feature SET GET?= 2. You can "and" ErrorLevel checks together to check for a specific value. In this example, use ErrorLevel to see if the current drive is B:. GET YE Rem if it is at least 1 and not 2 or more, Rem then it is exactly 1 meaning B:. if ErrorLevel 1 if not ErrorLevel 2 goto ISB Echo The current drive is not B: goto exit :ISB Echo The current drive is B: :exit Page 82 Get MEMORY and SYSTEM Information GET 2.7 GET MEMORY and SYSTEM Information The commands BR, P, E, M, D, DV, 4, 7, A, and W obtain information about the operating system and hardware configuration. GET BR Get/Set Break Flag Syntax: GET BR [New flag] [/switches] Input: optional new flag - 1 = ON, 0 = OFF. Output: ErrorLevel - old break flag Environment - old break flag Switches: Global only GET BR checks and/or sets the DOS BREAK Flag. It works like some of the other get/set commands such as B and V. GET BR will report 1 if the BREAK Flag is ON, or 0 if it is OFF. In addition, GET BR 1 will turn it on, and GET BR 0 will turn it off. Although you can control BREAK with the DOS BREAK command, GET BR allows you to store the user setting and temporarily change it to suit your programming style. Of course, if you allow the user to BREAK out of your BATch file with DOS Ctrl-Break handling, you will not have the opportunity to reset it, but if you want to handle BREAK yourself and use /C regularly, then you can get, set, and restore the user BREAK Flag with GET BR. GET BR also gives you another method of communicating information from your CONFIG.SYS to your AUTOEXEC.BAT. You can set BREAK ON or OFF in CONFIG.SYS according to whatever you want it to mean, and use GET BR to check and optionally reset it in your AUTOEXEC.BAT, then take some action according to whether it was ON or OFF. EXAMPLES: 1. Save user Break flag setting so you can turn it off to help you do your own Ctrl-Break management with the /C switch. When finished, restore user's original flag setting. Rem set BREAK OFF and save old setting in variable BREAK=. GET BR 0 /VBREAK= Rem Now do whatever you want in the BATch file, such as: GET S "Enter your password: " /c Rem When finished, restore saved Break flag setting. GET BR %BREAK% Rem Don't forget to clear out the variable! SET BREAK= 2. Suppose in one CONFIG.SYS file you have BREAK=ON to indicate that you are configuring for your CAD program, and in another CONFIG.SYS file you have BREAK=OFF if you want to run your normal configuration. In your AUTOEXEC.BAT you can test the Break flag, set it to the setting you want, and take appropriate action, thus using just one AUTOEXEC for both configurations. GET BR Get/Set Break Flag Page 83 Rem Get break flag setting and turn it off. GET BR 0 if "%GET%"=="1" goto RUNCAD Rem Do your something else here. goto EXIT :RUNCAD Rem Run your CAD program here. :EXIT Page 84 Check for Printer(PRN) GET P GET P Check for printer(PRN) Syntax: GET P[E] "prompt" [/switches] Input: none Output: ErrorLevel - 1=yes, 0=no Environment - 1=yes, 0=no Switches: /X Disable PrtSc for GET PE only. P checks whether a printer is available and ready at LPT1 (PRN). 1=yes, 0=no. GET P[E] now takes an optional prompt. Thus you can announce to the user what is happening without a separate Echo; e.g. GET PE "Initializing the printer" The usual ECho switches /N and /A can be used. PE will also send the DOS BIOS initialization signal to the printer as it does during boot-up. This may not work if a print buffer or spooler is in use unless it can be bypassed. If your printer has an internal buffer this is a way to flush it. If PE reports no printer, then the print-screen operation (the Print Screen or Shift PrtSc key) will be disabled to prevent hanging the computer if the PrtSc key is inadvertently pressed. To enable print-screen again, run GET PE with a printer attached and ready. Customized printer status tests. GET P[E] will accept a numerical arg representing a byte value. This value will be "and"ed with the printer status byte, and the result returned in the ErrorLevel and the Environment. If a numerical arg is present GET PE will not affect the status of PrtSC, but it will still attempt to initialize the printer. Note that if you are using a print spooler or buffer, all bets are off. Everything depends on what is returned in response to Int 17h, Service 02. Printer status items that can be tested for. Sum the values to test for the items desired. Value Hex Item 1 $1 Time-out 8 $8 I/O Error 16 $10 Printer selected 32 $20 Out-of-paper signal 64 $40 Acknowledgement from printer 128 $80 Printer not busy (0 means busy) For GET PE only, the /X switch will force disabling of PrtSc whether a printer is attached or not. EXAMPLES: 1. Check to see if a printer is available. GET P if ErrorLevel 1 goto PRINTIT Echo Can't print, no printer available. GET P Check for Printer(PRN) Page 85 goto EXIT :PRINTIT copy filename.ext prn :EXIT 2. Initialize printer, clearing the buffer and setting the page setting to Top of Form (TOF). If no printer is available, the Print Screen function will be turned off. GET PE if ErrorLevel 1 goto PRINTIT Echo Can't print, no printer available. Echo The print screen function has been disabled. goto EXIT :PRINTIT Echo The printer has been initialized, internal buffer cleared. :EXIT 3. GET P 255 will return a value representing the sum of the values of all 1-bits in the printer status byte. 4. GET P 144 will indicate with either 0 or 144 whether the printer is available and ready for data. 5. Disable Shift-PrtSc: GET PE /X Enable Shift-PrtSc again but only if the PE test is 1: GET PE Page 86 Get Environment Size GET E GET E Get Environment Size Syntax: GET E[E] [/switches] Input: none Output: ErrorLevel - number of Environment bytes free, EE divides by 10. Environment - number of Environment bytes free Switches: /X Full Environment size E reports the number of bytes of Environment space that are available for use. If it might be over 255 use EE which divides the number of bytes by 10 for the ErrorLevel only, and can report up to 2550 bytes. Since GET makes extensive use of the Environment, it is always a good idea to use GET E at the beginning of the BATch file to determine whether there are enough bytes available for the use of GET in the BATch file. GET E can also report the full Environment size as an eXtra function with /X. GET E or GET EE with the /X switch will report the total bytes in the command processors Environment. If you are running under a secondary command processor, GET E or GET EE with the /M switch will report Environment information for the master Environment. One way to use this information is to be able to enlarge the Environment space available if GET E reports too little to do what you want to do. For example, suppose you need 100 bytes of Environement free, but GET E tells you there are only 50 bytes available. You can then find the total size of the Environment, and recursively invoke the command processor with the new size that you will need after finding out how big it was originally. See example 3 below. GET E will remove the GET or other variable specified with /V for GET E before measuring. That gives a better measure of how much space is available for GET variables. To provide for sufficient free environment space in the event the BATch file is being run from a "shell" you can now SET GET=(a large variable) in your AUTOEXEC or before loading the shell (PC Shell, Xtree, etc.), and when GET measures the environment it will clear out the GET variable and give you an accurate reading. EXAMPLES: 1. Suppose GET will require at least 15 bytes of Environment space for the variables it will create in your BATch file. Remember to include the space required by the variable name, the = sign, and a terminating zero byte that is automatically added internally. GET E if ErrorLevel 15 goto CONTINUE Echo Not enough free Environment space to run this BATch file. goto EXIT :CONTINUE Rem Continue with the BATch file :EXIT 2. A more primitive method of checking for environment space is to attempt to create a variable then see if it is there. This may result in the user seeing an "Out of environment space" message. GET E Get Environment Size Page 87 Rem Try to create a variable that will use 16 bytes of space. SET TEST=1234567890 if "%TEST%"=="1234567890" goto CONTINUE Echo Not enough free Environment space to run this BATch file. goto EXIT :CONTINUE Rem Don't forget to clear out your test variable SET TEST= Rem Continue with the BATch file. :EXIT 3. You need 100 bytes of Environment free: GET E Rem First time GET reports ErrorLevel : 50 Rem Then the second time through with enough space branch to CONTINUE IF ErrorLevel 100 goto CONTINUE GET E /X Rem Check for error to prevent infinite loop. IF not ErrorLevel 1 GOTO END Rem Add 112 bytes to original Env size. (use a multiple of 16). GET R "+" %GET% /W112 Rem Invoke a new command processor with increased Env and run BAT file. %COMSPEC% /E:%GET% /C%0 %1 %2 %3 %4 %5 Rem When the secondary command processor terminates, it will have Rem run this BATch file, so now we must exit. GOTO END :CONTINUE Rem Do your thing here. :END Page 88 Get Memory Free GET M GET M Get Memory Free Syntax: GET M[E] [/switches] Input: none Output: ErrorLevel - number of kilobytes free, ME divides by 10. Environment - number of kilobytes free Switches: Global only M reports the free memory available in kilobytes. ME divides by 10. EXAMPLES: 1. A BATch file can check if there is sufficient memory to run a program. GET M if errorlevel 150 goto CONTINUE Echo Not enough memory to run your program. goto EXIT :CONTINUE Rem Run your program here. :EXIT 2. Suppose your program requires 300kb of memory. GET ME if errorlevel 30 goto CONTINUE Echo Not enough memory to run your program. goto EXIT :CONTINUE Rem Run your program here. :EXIT GET D Get DOS Version Page 89 GET D Get DOS Version Syntax: GET D[E] [/switches] Input: none Output: ErrorLevel - First two digits of DOS Version times 10. Environment - Major Version, DE gives Minor Version. Switches: Global only D reports the DOS version. The ErrorLevel will contain a number such as 33 for DOS 3.3 and 3.31, or 50 for DOS 5.0. The Environment will contain the major version such as 3 for DOS 3.0, 3.1, 3.3, or 3.3. DE will report the minor version in the Environment such as 1 for DOS 3.1, 31 for DOS 3.31, or 0 for DOS 5.0. GET D reports 20 (or greater) in the Environment for OS/2 major version. GET DE will put a 2 digit minor in Environment (but not in ErrorLevel). EXAMPLES: 1. You're setting up a program for your clients and it requires something different depending on whether the DOS Version is later than or earlier than 3.1. GET D if ErrorLevel 31 goto DOS3 Rem Do what you need here for DOS 2.x or 3.0. goto EXIT :DOS3 Rem Do what you need here for DOS 3.1 and later. :EXIT 2. You are distributing a program that requires DOS 3.3 or later. GET D if ErrorLevel 33 goto DOSOK Echo This program requires DOS 3.3 or later. goto EXIT :DOSOK Rem Run your program here. :EXIT Page 90 DESQview Version GET DV GET DV Get DESQview Version Syntax: GET DV [/switches] Input: none Output: ErrorLevel - First two digits of DV Version times 10. Environment - Major Version Switches: Global only DV reports the DESQview version if DV is running or 0 if not. The ErrorLevel will contain a number such as 40 for DV 4.0 The Environment will contain the major version such as 4 for DV 4.0, 4.1, etc. EXAMPLE: 1. If DESQview is in control do one thing, if not do something else. Rem Find out if DV is running and store the information. GET DV /VDV= if "%DV%"=="0" goto to MSDOS Rem Run your DV dependent commands here. goto EXIT :MSDOS Rem Do something else here. :EXIT Rem Clear out the DV variable SET DV= GET 7 Check Coprocessor Page 91 GET 7 Check Coprocessor/CPU Syntax: GET 7[E] [/switches] Input: none Output: ErrorLevel - 7: Math Coprocessor Installed - 7E: type of CPU. Environment - Character representation of ErrorLevel number. Switches: Global only 7 reports whether a math coprocessor is installed. 1=yes, 0=no. 7E reports the CPU chip type - 0 for 8088/86, 2 for 80286, or 3 for 80386 or later. EXAMPLES: 1. Run a faster version of a mathematical program if a coprocessor is installed. GET 7 if ErrorLevel 1 goto NDP Rem Run the slower version here goto EXIT :NDP Rem Run the faster version here :EXIT 2. Run the 386 version of a program if the CPU is an 80386 or later. GET 7E if ErrorLevel 3 goto IS386 Rem Run the non-386 version here goto EXIT :IS386 Rem Run the 386 version here :EXIT Page 92 Check 4DOS/Windows GET 4 GET 4 Check 4DOS/Windows Syntax: GET 4[E] [/switches] Input: none Output: ErrorLevel - 4: 4DOS version number. 4E: Windows. Environment - Character representation of ErrorLevel number. Switches: Global only 4 Checks whether 4DOS or [4E] Windows is currently running and returns the 4DOS version number. The ErrorLevel will contain a number such as 40 for 4DOS 4.0. The Environment will contain the major version such as 4 for 4DOS 4.0, 4.1, etc. 4E will report the minor version in the Environment such as 1 for 4DOS 4.1 or 0 for 4DOS 5.0. The 4DOS Version number only indicates that 4DOS is in memory, not necessarily that it is the parent of the BATch program, but you can check for that with the test given in the 4DOS manual: if not "%_cwd%"=="" echo 4DOS is loaded! Although 4DOS provides a method to make this check directly with BATch commands, it may be a convenience to use GET to obtain and store the information in the same command. 4DOS provides a lot of services for BATch files, and some DOS-like commands have extra features, but if the BATch file might be run on a system that is not using 4DOS for the command processor those extra features can't be used. 4E returns 1 if Windows is running or 0 if not. Some DOS commands, such as CHKDSK, must not be run if Windows is running. You can use the GET 4E command to avoid these problems. EXAMPLES: 1. If 4DOS is the command processor, use some of its special features. If not, make do the best you can with COMMAND.COM and GET. Rem Find out if 4DOS is running and store the information. GET 4 /V4DOS= if "%4DOS%"=="0" goto to MSDOS Rem Run your 4DOS enhanced commands here. goto EXIT :MSDOS Rem Do the best you can with MS DOS with GET here. :EXIT Rem Clear out the 4DOS variable SET 4DOS= 2. Make a cover for CHKDSK to avoid damaging your disk if Windows is running. Since CHKDSK is an external command, you can rename it to something else to avoid running it inadvertently. Suppose we rename it CHEKDISK.EXE and call this BATch file CHKDSK.BAT. @Echo off Rem This file is CHKDSK.BAT, a cover for DOS CHKDSK. get 4E if ErrorLevel 1 goto WINDOWS CHEKDISK %1 %2 %3 goto EXIT GET 4 Check 4DOS/Windows Page 93 :WINDOWS Echo Don't run CHKDSK when WINDOWS is running! :EXIT Page 94 Check for ANSI.SYS/Model GET A GET A Check for ANSI.SYS/Model Syntax: GET A[E] [/switches] Input: none Output: ErrorLevel - A: ANSI.SYS - AE: ROM BIOS Model Byte/BIOS Date Environment - A: 1=yes, 0=no - AE: Hexadecimal Model Byte/Date Switches: Global only A reports whether ANSI.SYS is loaded. If you are using an ANSI.SYS clone, check to see if it works with yours. AE will return the ROM BIOS model byte (a 2-character machine code) followed by a space, then the 8-byte BIOS date. At this time the documented model bytes listed in "The NEW Peter Norton's Programmer's Guide to the IBM PC and PS/2," (Page 64) are: FF(255)=PC(1981) FE(254)=PC or PC/XT(1982) FD(253)=PCjr(1983) FC(252)=PC/AT(1984-85),PC/XT Model 286(1986),PS/2 Model 50/60(1987) FB(251)=PC/XT(1986) FA(250)=PS/2 Model 25(1987)/30(1986) F9(249)=PC Convertible F8(248)=PS/2 Model 80(1987) (Example: An 80386 AT clone is an FC, ErrorLevel 252). EXAMPLES: 1. If the computer is running ANSI.SYS you can use it to provide special screen effects. For example, 4DOS has commands that take advantage of the features of ANSI.SYS that won't work if ANSI.SYS isn't loaded. Rem Check for ANSI.SYS and store the result in ANSI= GET A /VANSI= 2. If you are supporting several computers and they are different models, you may be able to determine which one is running the BATch file by reading the model byte. GET AE if ErrorLevel 254 goto NOSUPP if ErrorLevel 253 goto PCJR if ErrorLevel 252 goto ATCLONE if ErrorLevel 249 if not ErrorLevel 250 goto CONVERT :NOSUPP Echo This computer is not supported goto EXIT :ATCLONE Rem Do things for AT Clone here goto EXIT :CONVERT Rem Do things for IBM Convertible here goto EXIT :PCJR Rem Do things for the PC Jr. here :EXIT GET W Warm/Cold Boot Page 95 GET W Warm/Cold Boot Syntax: GET W[E] "prompt" [arg] [/switches] Input: any argument to just report type of last boot. Output: ErrorLevel - If arg, 1=warm, 0=cold Environment - If arg, 1=warm, 0=cold Switches: The usual ECho switches /N and /A if a prompt is specified. W will reboot the computer as if the 3-finger salute (Ctrl-Alt-Del) was pressed unless an arg is given. WE will reboot as if the computer was turned off then on again unless an argument is given. If any characters are present as an argument with W or WE, GET will attempt to determine if the preceding boot was warm or cold instead of rebooting. This does not work on all machines. It depends on whether the booting procedure clears a certain memory location - it worked on my XT but not on my 386, for example. If successful, a 1 indicates the previous boot was warm, 0 means it was a cold boot. GET W will take a prompt. If a "prompt" is specified, GET C is called internally to wait for a character to be entered. The switches for GET C including /W, /C, and /A can be used. If /C is not specified the user can break out with Ctrl-Break or Ctrl-C. To prevent this, use /C. When a valid character is entered, the specified type of reboot will be initiated. Using a prompt nullifies the effect of an argument which modifies GET W to just try to determine whether the last boot was warm or cold. As with GET C, if an invalid character is entered, the waiting time will be infinite. EXAMPLES 1. Copy in a new AUTOEXEC.BAT and CONFIG.SYS and warm boot. copy autoexec.new autoexec.bat copy config.new config.sys get w 2. Ask for a password, if it is wrong cold boot the computer. get S "Enter password now: " TTTTTTTT if "%GET%"=="PASSWORD" goto OK get we OK: Rem Password was correct, continue. 3. Perform a CHKDSK if a cold boot but not a warm boot - may only work on XT class machines. GET W xxx if ErrorLevel 1 CHKDSK Page 96 The Environment and Shells GET 2.7 The Environment and Shells This is a brief, general discussion of the DOS Environment for those who may not be sufficiently familiar with it. The DOS Environment is a small area (usually) of memory that DOS automatically allocates to every program that it is asked to load or run. The "master" Environment is the original Environment allocated to COMMAND.COM or 4DOS or whichever command processor you are using. The original size of the Environment can be set in later versions of DOS by using the SHELL command in your CONFIG.SYS file. However, the setting of Environment size is not a SHELL command function, but is a command processor option. For example, the COMMAND.COM /E: switch lets you set the size if you are using COMMAND.COM as your command processor. For documentation look under such topics as SHELL, COMMAND, and "Configuring Your System" in your DOS manual. Since most new programs make extensive use of the Environment, it is important to be sure enough Environment space is allocated to accommodate them all. If you see the error message "Out of Environment Space", you know that you do not have enough allocated. You can view the contents of the Environment by issuing the SET command of DOS with no arguments at the DOS prompt. You will see a sequence of variable names, each followed by the "=" sign and the string value assigned to the variable. For example, COMSPEC=C:\COMMAND.COM. You can also store string information in the Environment with the SET command by specifying it in the same manner as it is displayed. For example, SET PATH=C:\;C:\DOS. Do not place any spaces on either side of the "=" sign unless you intend for the space to be either a part of the variable name or a part of the string. When DOS loads and runs a COM or EXE program file, that program receives a copy of the Environment as it is at that time, trimmed down so that only a few bytes remain free. This copy does not change unless the program that owns it changes it. While COMMAND.COM and 4DOS are true shells, many users run programs from within other programs also known as "shells". These include programs such as PC Shell from Central Point's PC Tools, The Norton Commander, Xtree, and many others. Note that these DOS "shells" shield the master Environment from programs that are executed by the shell. If you find that to be the case, the information will usually be available to the BATch file from the Environment of the secondary command processor loaded by the shell as is usually necessary to run a BATch file. Except for the /M switch, GET only attempts to locate the Environment of the command processor that is running the BATch file, so the Environment information can disappear if the shell or the secondary command processor is terminated. GET attempts to place the information where the BATch file can locate it since that is its primary purpose. Out of Environment Space When running a BATch file from a "shell" there may be problems with "Out of Environment space" since DOS does not usually allocate excess Environment space to child processes. 4DOS and its alter-ego NDOS provide a means to ensure that copies of the Environment have sufficient space available, but COMMAND.COM is very stingy with the amount of free Environment space it allocates to child processes. Check the documentation for your shell program to see if it can make sufficient GET 2.7 The Environment and Shells Page 97 Environment space available. If you plan on running a BATch file from a shell and find that "Out of environment space" is a problem, there are several things that you can try to do. If COMMAND.COM is your command processor, in order to run your.bat you can tell your shell to use the command, C:\COMMAND.COM /E:512 /Cyour.bat. Assuming that COMMAND.COM is in the root directory of the C: drive, this will allocate 512 bytes of Environment space to your BATch file. Just adjust the command for the proper location of your COMMAND.COM and the actual amount of Environment space you will need with the /E: switch. If your shell won't cooperate in running COMMAND.COM in this manner, then you can establish a BATch file to do it for you. Call it RUNBATCH.BAT and make the first line %COMSPEC% /E:512 /C%1 %2 %3 etc. Then when you want to run your.bat, tell your shell to execute the command RUNBATCH your.bat. Follow that with any parameters you need for your.bat and they will be picked up by the %1 %2 %3 etc. replaceable parameters in RUNBATCH.BAT. Another method to ensure that GET has enough Environment space to store its results is to establish a dummy GET variable before loading any shells or other programs. The best way would be to do it in your AUTOEXEC.BAT. Simply insert the command SET GET=xxxxx...xxxx in your AUTOEXEC.BAT file with enough x's or other characters for the maximum length input string you are expecting. Then in any BATch file that is to be run from the shell, before using GET issue the command SET GET=. This will remove the GET variable from the Environment and free the space to be reused by GET. One recurring reason for this problem is running the BATch file from a so- called "shell" - Windows, PC Shell, Norton Commander, Xtree, etc.. When you run a BATch file from a shell, it invokes a second copy of COMMAND.COM (a true shell), but DOS is stingy with the environment space it passes to a "child" program such as this second copy of COMMAND.COM. There are a couple of solutions - if this is, in fact, the problem. 1. If you can get your shell to run your BATch file with the command C:\COMMAND.COM /E:1024 /Cyourbat then you can specify how much environment space you want with the /E:nnn parameter. Of course put in the real name and location of your command processor where I have put C:\COMMAND.COM. 2. In your autoexec set a large dummy variable in your Environment with the SET command, such as SET DUMMY=a large variable here but make it longer. Then when you run a BATch file from a shell, make the first statement in the BATch file SET DUMMY= and it will clear up the space for use by GET. 3. Use 4DOS or NDOS for your command processor instead of COMMAND.COM. 4DOS and its alter-ego NDOS allow you to specify how much free environment space you want for child processes. Only 4DOS does it the way it should be done. MS never has handled the Environment space problem very well. 4. See examples for GET E showing how to run your BATch file recursively by invoking a secondary command processor yourself. Page 98 Program Information GET 2.7 PROGRAM INFORMATION GET is programmed in assembly language for MS-DOS computers. It was assembled with Borland's Turbo Assembler, and compressed with a file compression utility. GET is designed to be small and fast to provide rapid response in BATch files and not take up too much room on floppy disks, consequently it does not do extensive error checking. Nothing in GET is known to cause harm, but if parameters are not used in accordance with the documentation the results may not be what you expect. GET is designed for productive use by BATch programmers, not for casual use from the keyboard. In most applications there will be no noticeable slowing down of BATch file execution due to the use of GET. Most versions of DOS read and execute lines of BATch files one at a time. This is the slowest part of the BATch execution process. Providing there are sufficient DOS buffers or a disk cache, GET will remain available in the buffers or cache in memory and execute instantaneously when loaded by DOS. Some additional speedup may be noticed if it is possible to locate GET.EXE and/or your BATch file on a virtual disk in RAM such as on a RAMDRIVE or VDISK. RUNTIME Version for Registered users --------------------------------------------------------------- Registered users of GET receive a registered RUNTIME module that is smaller and may provide additional speed in execution. It is not burdened with the over 2K of Help screens so may load slightly faster when invoked. The registered runtime version does not display the copyright notice unless it is called with no valid arguments, and is under 6K in size. For the convenience of registered users who are developing BATch files, and want to use the runtime module for development to avoid the periodic display of the copyright notice, the GET?=ON feature has been added to the runtime module. With GET?=ON either GET module will report the values that it places in the Environment and the ErrorLevel for debugging purposes. If you do use the runtime module as suggested, yet you like to have the help screens from the shareware module available for use, I suggest using one of the following methods: (a) Use redirection to capture the help screens to a file and use a text editor or file viewer to read the file. It is very useful to load this file into a window in your text editor when you are editing BATch files for quick reference. (b) Keep GET27.EXE in your path and run it when you want to view the help screens. LICENSING AND DISTRIBUTION If you like GET and would like to help support development of inexpensive software, please send a contribution to the address below. Thank you for any support you care to provide. If you send $15 or more (plus appropriate shipping and tax) you will receive the following benefits: The latest version of GET with any new features. A smaller runtime version to distribute with your BATch files. A single user license with no royalties for use of the runtime version. GET 2.7 Program Information Page 99 Optional purchase of a printed copy of this manual. Free support by BBS, mail, phone, or CompuServe (see below). Notification of new releases and upgrades. Reduced prices for upgrades. See ORDER.GET for pricing information. California residents please add applicable sales tax. See the SPECIAL OFFER below for a discount on registering both GET and MASDIR. If you have a modem, VISA and MASTERCARD registrations can be entered via NITELOG BBS, 408-655-1096. After completing the brief sign-on registration, enter S for Script, then 3 for Script 3 and provide the requested information. CORPORATE users must obtain a site license from me for in-house use. See the file ORDER.GET for pricing and ordering information. None of the above licensing terms includes using GET in conjunction with the distribution of a commercial (retail) software product other than shareware, user-supported, or public domain software. To use GET in conjunction with the distribution of a retail software product you must obtain either a site license or a distribution license. Call or message for quotes if you are interested or have any questions. BBS SYSOPs, PC User Groups, and shareware authors and distributors are hereby granted a single user license to use GET for their own purposes. If such persons are registered users of GET they may freely distribute unmodified copies of this version of GET.EXE and all of the associated files in GET27.ZIP. If an unregistered version of GET is used in conjunction with the distribution of a shareware or public domain software product, the distribution disk must include GET27.ZIP. VENDORS who already have my permission to distribute my shareware products have permission to distribute GET. Other vendors must contact me for permission by sending me a request accompanied with a current catalog or other list of offerings. REGISTERED users of GET may use and distribute GET in accordance with these rules. GETRUN.EXE is a runtime version of GET available only to registered users. It omits the online help screens so is considerably smaller and runs in less memory. GET is not a TSR so the memory is in use only while GET is actually running. 1. GET.EXE may be freely distributed provided the distribution disk includes all *.DOC and other GET distribution files. Such distribution must not include GETRUN.EXE under any name. 2. If you are a licensed user of GETRUN.EXE, up to the licensed number of copies of GETRUN.EXE may be renamed GET.EXE and used in conjunction with distributed BATch files, provided that none of the .DOC files are included on any disk in the distribution package. For non-commercial use, licensed users may use an unlimited number of copies. Other registered users may obtain an inexpensive distribution license in addition to a site or single user license. 3. GET.EXE and the .DOC files must never be included in any distribution that includes GETRUN.EXE no matter what names are used for these files. Page 100 MASDIR, The MASter DIRectory System GET 2.7 SPECIAL OFFER If you like GET please try MASDIR! MASDIR (pronounced 'master') the MASter DIRectory System, is a general purpose sorted directory program with unique customization and disk label printing features. If you ever use DIR, you should do yourself a favor and take a look at MASDIR! MASDIR is not a "shell". The main program, SDL.COM, is one of the best sorted directory programs anywhere. The setup program allows you to set the many defaults to your own specifications, including customizing the titles that appear in the header. In addition, you can print disk labels and/or sleeve inserts for 5.25" and 3.5" diskettes. This really saves you a lot of time when you are looking through your collection of diskettes for a particular file. They are all listed conveniently along with your own description in the title lines. You can also create disk file catalogs of your diskettes and directories that you can then annotate to describe individual files, and search with your editor or listing program. Additional features include listing only subdirectories or not listing them at all, listing only files created today or within a specified period, reverse sorting for any of the sort options, the amount of space a group of files will occupy for different cluster sizes, support for DR DOS and 4DOS, SETting defaults in the Environment, enter two file specifications such as *.COM *.EXE, paging up and down in large directories, show only files that have not been backed up (archive bit set), and many more. As of the above date, the current release of MASDIR is Version 5.4. It is a shareware program that is available on bulletin boards, GENIE, CompuServe, The Public (software) Library, PC-SIG, and from other distributors of public domain and shareware programs. If you cannot conveniently locate a copy, I will be happy to send you one. Just contact me as indicated above. The registration fee for MASDIR is $19 including shipping and handling for the program, plus one unit of labels free. Please include $2 S&H only if you order any amount of labels. Register both GET and MASDIR and take a 15% discount. Use the order form and indicate that you want both MASDIR and GET for just $25, instead of $30. Then complete the rest of the form for any other items you want. Thank you for your kind attention. Questions, comments, and suggestions are always welcome. Contact us at: MOBY DISK: 1021 San Carlos Road, Pebble Beach, CA 93953 Phone: (408) 646-1899 COMPUSERVE:72357,2276 America Online: MobyDisk2 Internet: bob.stephan@nitelog.com BBS: Nitelog 408-655-1096 BBS: The Cricket 408-373-3773 /s/ Bob Stephan May 29, 1995 Page A ASCII and Scan Codes Appendix A Keyboard Codes Recognized by GET ┌────────────────────────────────────┬──────────────────────────────────────┐ │ Function Key Scan Codes(1) │ Alphabetic & Other ASCII Keys │ │Key Normal Shift Control Alt │ Key/ Normal Shift Control Alt(1)│ │F1 59 84 94 104 │ Shift ASCII ASCII ASCII Scan│ │F2 60 85 95 105 │ Tab 9 15 148(s) 165│ │F3 61 86 96 106 │ a 97 65 1 30│ │F4 62 87 97 107 │ b 98 66 2 48│ │F5 63 88 98 108 │ c 99 67 3 46│ │F6 64 89 99 109 │ d 100 68 4 32│ │F7 65 90 100 110 │ e 101 69 5 18│ │F8 66 91 101 111 │ f 102 70 6 33│ │F9 67 92 102 112 │ g 103 71 7 34│ │F10 68 93 103 113 │ h 104 72 8 35│ │F11 133 135 137 139 │ i 105 73 9 23│ │F12 134 136 138 140 │ j 106 74 10 36│ ├────────────────────────────────────┤ k 107 75 11 37│ │ Number & Top Row Keys │ l 108 76 12 38│ │Key/ Normal Shift Control Alt(1)│ m 109 77 13 50│ │Shift ASCII ASCII ASCII Scan │ n 110 78 14 49│ │ `/~ 96 126 - 41 │ o 111 79 15 24│ │ 1/! 49 33 - 120 │ p 112 80 16 25│ │ 2/@ 50 64 3(s) 121 │ q 113 81 17 16│ │ 3/# 51 35 - 122 │ r 114 82 18 19│ │ 4/$ 52 36 - 123 │ s 115 83 19 31│ │ 5/% 53 37 - 124 │ t 116 84 20 20│ │ 6/^ 54 94 30 125 │ u 117 85 21 22│ │ 7/& 55 38 - 126 │ v 118 86 22 47│ │ 8/* 56 42 - 127 │ w 119 87 23 17│ │ 9/( 57 40 - 128 │ x 120 88 24 45│ │ 0/) 48 41 - 129 │ y 121 89 25 21│ │ -/_ 45 95 31 130 │ z 122 90 26 44│ │ =/+ 61 43 - 131 │ [/{ 123 91 27 26│ │ \/| 92 124 28 43 │ ]/} 125 93 29 27│ │BkSp 8 8 127 14 │ ;/: 59 58 - 39│ ├────────────────────────────────────┤ '/" 39 34 - 40│ │ Cursor Pad & Grey Key Codes │ ,/< 44 60 - 51│ │Key Normal Shift Control Alt(1)│ ./> 46 62 - 52│ │PrtSc - - 114 - │ //? 47 63 - 53│ │Insert - - - 162 ├──────────────────────────────────────┤ │Home - - - 151 │ Number Pad (NumLock On(2)) Codes │ │PageUp - - - 153 │ Key Normal(2) Shift(2) Control Alt(3)│ │Delete - - - 163 │ 0/Ins 48 82 146 AltNum│ │End - - - 159 │ 1/End 49 79 117 AltNum│ │PageDown - - - 161 │ 2/Down 50 80 145 AltNum│ │UpArrow - - - 152 │ 3/PgDn 51 81 118 AltNum│ │LeftArrow - - - 155 │ 4/Left 52 75 115 AltNum│ │DownArrow - - - 160 │ 5 53 76 143 AltNum│ │RightArrow - - - 157 │ 6/Right 54 77 116 AltNum│ │ / 47(a) 47(a) 149 164 │ 7/Home 55 71 119 AltNum│ │ * 42(a) 42(a) 150 55 │ 8/Up 56 72 141 AltNum│ │ - 45(a) 45(a) 142 74 │ 9/PgUp 57 73 132 AltNum│ │ + 43(a) 43(a) 144 78 │ ./Del 46 83 147 AltNum│ │NumEnter 125(4) 125(4) 10(a) 166 │--------------------------------------│ │Esc 126(4) 126(4) 126(4) 1 │(2)With NumLock Off swap Normal/Shift.│ │Enter 125(4) 125(4) 10(a) 28 │(3)AltNum keys enter ASCII characters.│ └────────────────────────────────────┴──────────────────────────────────────┘ (s) indicates scan code, (a) indicates ASCII code where not readily apparent. (1)To use extended/enhanced keys with GET C and GET T, add 100 to the scan code. Scan codes of 28 through 150 are reported as surrogates 128 through 250. To use extended and enhanced keys with GET U, add 255 to the scan code. Many of the scan codes 28 through 150 are recognized as surrogates 283 through 405. (4)Surrogate values for use with GET C and GET T. Also, space will return 255. ASCII Table ┌───────────────────┬────────────┬───────────┬────────────┬────────────┐ │ Dec Char Code │ Dec Char │ Dec Char │ Dec Char │ Dec Char │ ├───────────────────┼────────────┼───────────┼────────────┼────────────┤ │ 0 NUL │ 32 Space │ 64 @ │ 96 ` │ 128 Ç │ │ 1 Ctrl-a │ 33 ! │ 65 A │ 97 a │ 129 ü │ │ 2 Ctrl-b │ 34 " │ 66 B │ 98 b │ 130 é │ │ 3 Ctrl-c │ 35 # │ 67 C │ 99 c │ 131 â │ │ 4 Ctrl-d │ 36 $ │ 68 D │ 100 d │ 132 ä │ │ 5 Ctrl-e │ 37 % │ 69 E │ 101 e │ 133 à │ │ 6 Ctrl-f │ 38 & │ 70 F │ 102 f │ 134 å │ │ 7 Ctrl-g Bell │ 39 ' │ 71 G │ 103 g │ 135 ç │ │ 8 Ctrl-h BkSp │ 40 ( │ 72 H │ 104 h │ 136 ê │ │ 9 Ctrl-i Tab │ 41 ) │ 73 I │ 105 i │ 137 ë │ │ 10 Ctrl-j LF │ 42 * │ 74 J │ 106 j │ 138 è │ │ 11 Ctrl-k │ 43 + │ 75 K │ 107 k │ 139 ï │ │ 12 Ctrl-l FF │ 44 , │ 76 L │ 108 l │ 140 î │ │ 13 Ctrl-m CR │ 45 - │ 77 M │ 109 m │ 141 ì │ │ 14 Ctrl-n │ 46 . │ 78 N │ 110 n │ 142 Ä │ │ 15 Ctrl-o │ 47 / │ 79 O │ 111 o │ 143 Å │ │ 16 Ctrl-p │ 48 0 │ 80 P │ 112 p │ 144 É │ │ 17 Ctrl-q │ 49 1 │ 81 Q │ 113 q │ 145 æ │ │ 18 Ctrl-r │ 50 2 │ 82 R │ 114 r │ 146 Æ │ │ 19 Ctrl-s │ 51 3 │ 83 S │ 115 s │ 147 ô │ │ 20 Ctrl-t │ 52 4 │ 84 T │ 116 t │ 148 ö │ │ 21 Ctrl-u │ 53 5 │ 85 U │ 117 u │ 149 ò │ │ 22 Ctrl-v │ 54 6 │ 86 V │ 118 v │ 150 û │ │ 23 Ctrl-w │ 55 7 │ 87 W │ 119 w │ 151 ù │ │ 24 Ctrl-x │ 56 8 │ 88 X │ 120 x │ 152 ÿ │ │ 25 Ctrl-y │ 57 9 │ 89 Y │ 121 y │ 153 Ö │ │ 26 Ctrl-z │ 58 : │ 90 Z │ 122 z │ 154 Ü │ │ 27 Ctrl-[ Esc │ 59 ; │ 91 [ │ 123 { │ 155 ¢ │ │ 28 Ctrl-\ │ 60 < │ 92 \ │ 124 | │ 156 £ │ │ 29 Ctrl-] │ 61 = │ 93 ] │ 125 } │ 157 ¥ │ │ 30 Ctrl-^ │ 62 > │ 94 ^ │ 126 ~ │ 158 ₧ │ │ 31 Ctrl-_ │ 63 ? │ 95 _ │ 127 DEL │ 159 ƒ │ └───────────────────┴────────────┴───────────┴────────────┴────────────┘ ┌──────────┬───────────┬───────────┬───────────┬───────────┬───────────┐ │ Dec Char │ Dec Char │ Dec Char │ Dec Char │ Dec Char │ Dec Char │ ├──────────┼───────────┼───────────┼───────────┼───────────┼───────────┤ │ 160 á │ 176 ░ │ 192 └ │ 208 ╨ │ 224 α │ 240 ≡ │ │ 161 í │ 177 ▒ │ 193 ┴ │ 209 ╤ │ 225 ß │ 241 ± │ │ 162 ó │ 178 ▓ │ 194 ┬ │ 210 ╥ │ 226 Γ │ 242 ≥ │ │ 163 ú │ 179 │ │ 195 ├ │ 211 ╙ │ 227 π │ 243 ≤ │ │ 164 ñ │ 180 ┤ │ 196 ─ │ 212 ╘ │ 228 Σ │ 244 ⌠ │ │ 165 Ñ │ 181 ╡ │ 197 ┼ │ 213 ╒ │ 229 σ │ 245 ⌡ │ │ 166 ª │ 182 ╢ │ 198 ╞ │ 214 ╓ │ 230 µ │ 246 ÷ │ │ 167 º │ 183 ╖ │ 199 ╟ │ 215 ╫ │ 231 τ │ 247 ≈ │ │ 168 ¿ │ 184 ╕ │ 200 ╚ │ 216 ╪ │ 232 Φ │ 248 ° │ │ 169 ⌐ │ 185 ╣ │ 201 ╔ │ 217 ┘ │ 233 Θ │ 249 ∙ │ │ 170 ¬ │ 186 ║ │ 202 ╩ │ 218 ┌ │ 234 Ω │ 250 · │ │ 171 ½ │ 187 ╗ │ 203 ╦ │ 219 █ │ 235 δ │ 251 √ │ │ 172 ¼ │ 188 ╝ │ 204 ╠ │ 220 ▄ │ 236 ∞ │ 252 ⁿ │ │ 173 ¡ │ 189 ╜ │ 205 ═ │ 221 ▌ │ 237 φ │ 253 ² │ │ 174 « │ 190 ╛ │ 206 ╬ │ 222 ▐ │ 238 ε │ 254 ■ │ │ 175 » │ 191 ┐ │ 207 ╧ │ 223 ▀ │ 239 ∩ │ 255 Blank │ └──────────┴───────────┴───────────┴───────────┴───────────┴───────────┘ NOTE: Upper ASCII characters (above 127) can be formed by holding the Alt key down while spelling out the decimal value on the number pad. When the Alt key is released, the ASCII character will be displayed. See the documentation for your text editor for the method it uses to enter control and upper ASCII values. Scan Code Table(1) Extended and enhanced keys are recognized by their scan codes. This scan code table lists all known scan codes for the 101 enhanced keyboard. GET C and GET T use the upper ASCII characters as surrogates for some of the extended and enhanced keys. GET forms these surrogates for many of the scan codes in the range of 28 through 150 by adding 100 to the scan code and using the corresponding upper ASCII character. For example, the scan code for F1 is 59. This would be confused with the ASCII character <;>, so GET adds 100 to it and uses code 159 which is represented by the upper ASCII character <ƒ>. ┌────────────────┬─────────────────┬────────────────┬────────────────────┐ │ Code Key │ Code Key │ Code Key │ Code Key │ ├────────────────┼─────────────────┼────────────────┼────────────────────┤ │ 1 Esc │ 43 Alt-\/| │ 85 Shift-F2 │ 127 Alt-8 │ │ 2 1/! │ 44 Alt-z │ 86 Shift-F3 │ 128 Alt-9 │ │ 3 2/@ │ 45 Alt-x │ 87 Shift-F4 │ 129 Alt-0 │ │ 4 3/# │ 46 Alt-c │ 88 Shift-F5 │ 130 Alt-- │ │ 5 4/$ │ 47 Alt-v │ 89 Shift-F6 │ 131 Alt-= │ │ 6 5/% │ 48 Alt-b │ 90 Shift-F7 │ 132 CtrlPgUp │ │ 7 6/^ │ 49 Alt-n │ 91 Shift-F8 │ 133 F11 │ │ 8 7/& │ 50 Alt-m │ 92 Shift-F9 │ 134 F12 │ │ 9 8/* │ 51 Alt-,/< │ 93 Shift-F10│ 135 Shift-F11 │ │ 10 9/( │ 52 Alt-./> │ 94 Ctrl-F1 │ 136 Shift-F12 │ │ 11 0/) │ 53 Alt-//? │ 95 Ctrl-F2 │ 137 Ctrl-F11 │ │ 12 -/_ │ 54 RightShift│ 96 Ctrl-F3 │ 138 Ctrl-F12 │ │ 13 =/+ │ 55 Grey* │ 97 Ctrl-F4 │ 139 Alt-F11 │ │ 14 BkSp │ 56 LeftAlt │ 98 Ctrl-F5 │ 140 Alt-F12 │ │ 15 Tab │ 57 Space │ 99 Ctrl-F6 │ 141 CtrlUp │ │ 16 Alt-q │ 58 CapsLock │ 100 Ctrl-F7 │ 142 CtrlGrey- │ │ 17 Alt-w │ 59 F1 │ 101 Ctrl-F8 │ 143 Ctrl-Num5 │ │ 18 Alt-e │ 60 F2 │ 102 Ctrl-F9 │ 144 CtrlGrey+ │ │ 19 Alt-r │ 61 F3 │ 103 Ctrl-F10 │ 145 CtrlDown │ │ 20 Alt-t │ 62 F4 │ 104 Alt-F1 │ 146 CtrlIns │ │ 21 Alt-y │ 63 F5 │ 105 Alt-F2 │ 147 CtrlDel │ │ 22 Alt-u │ 64 F6 │ 106 Alt-F3 │ 148 CtrlTab │ │ 23 Alt-i │ 65 F7 │ 107 Alt-F4 │ 149 CtrlGrey/ │ │ 24 Alt-o │ 66 F8 │ 108 Alt-F5 │ 150 CtrlGrey* │ │ 25 Alt-p │ 67 F9 │ 109 Alt-F6 │ 151 AltGreyHome │ │ 26 [/{ │ 68 F10 │ 110 Alt-F7 │ 152 AltGreyUp │ │ 27 ]/} │ 69 NumLock │ 111 Alt-F8 │ 153 AltGreyPgUp │ │ 28 Alt-Enter│ 70 ScrollLock│ 112 Alt-F9 │ 154 │ │ 29 LeftCtrl │ 71 Home │ 113 Alt-F10 │ 155 AltGreyLeft │ │ 30 Alt-a │ 72 Up │ 114 CtrlPrtSc│ 156 │ │ 31 Alt-s │ 73 PgUp │ 115 CtrlLeft │ 157 AltGreyRight│ │ 32 Alt-d │ 74 Grey- │ 116 CtrlRight│ 158 │ │ 33 Alt-f │ 75 Left │ 117 CtrlEnd │ 159 AltGreyEnd │ │ 34 Alt-g │ 76 Num5 │ 118 CtrlPgDn │ 160 AltGreyDown │ │ 35 Alt-h │ 77 Right │ 119 CtrlHome │ 161 AltGreyPgDn │ │ 36 Alt-j │ 78 Grey+ │ 120 Alt-1 │ 162 AltGreyIns │ │ 37 Alt-k │ 79 End │ 121 Alt-2 │ 163 AltGreyDel │ │ 38 Alt-l │ 80 Down │ 122 Alt-3 │ 164 AltGrey-/ │ │ 39 Alt-;/: │ 81 PgDn │ 123 Alt-4 │ 165 AltTab │ │ 40 Alt-'/" │ 82 Ins │ 124 Alt-5 │ 166 AltGreyEnter│ │ 41 Alt-`/~ │ 83 Del │ 125 Alt-6 │ │ │ 42 LeftShift│ 84 Shift-F1 │ 126 Alt-7 │ │ └────────────────┴─────────────────┴────────────────┴────────────────────┘ (1)To use extended and enhanced keys with GET C and GET T, add 100 to the scan code. Many of scan codes 28 through 150 are recognized as surrogates 128 through 250. To use extended and enhanced keys with GET U, add 255 to the scan code. Many of scan codes 28 through 150 are recognized as surrogates 283 through 405.